AskClean

Como apagar node_modules no Mac sem perder seu projeto

Equipe AskClean · Atualizado 2026-11-02

Você pode apagar a pasta node_modules de um projeto se o package.json e o lockfile correto estiverem intactos e as dependências continuarem disponíveis. Meça cada projeto primeiro, encerre as ferramentas em execução e mova para o Lixo só a pasta de dependências confirmada. Depois, reinstale com o mesmo gerenciador de pacotes e só esvazie o Lixo quando o build, os testes e o app voltarem a funcionar.

Braço robótico move um bloco de uma rede de dependências para uma caixa de reciclagem, ao lado de um bloco protegido, um diagrama do projeto e um cadeado
Remova só a pasta de dependências que pode ser reconstruída; preserve o manifesto, o lockfile, a configuração e o código-fonte.

Separe node_modules do projeto e do cache

A pasta node_modules contém a árvore de dependências instalada de um projeto e só pode ser reconstruída enquanto todos os insumos continuarem disponíveis. Ao apagá-la, o projeto deixa de executar e de compilar até a reinstalação terminar. O package.json, os lockfiles, o código-fonte, a configuração, os patches, os arquivos de workspace e o histórico do Git são a receita da reinstalação e não devem ser apagados. O cache compartilhado de downloads do npm, normalmente em ~/.npm, é outra categoria de armazenamento.

Confirme que as dependências podem ser reconstruídas

Um lockfile torna a reinstalação mais previsível, mas não é uma cópia dos pacotes. Confirme o gerenciador de pacotes e a versão usados no projeto e o acesso a registries privados, à VPN, a dependências Git e file:, a workspaces locais, a downloads externos e às toolchains nativas. O npm v12 não lê mais o npm-shrinkwrap.json: se esse for o único lockfile de um projeto legado, renomeie-o para package-lock.json, que tem o mesmo formato, antes de usar o npm v12. Se já existir um package-lock.json, não o sobrescreva; compare e reconcilie os dois arquivos numa alteração separada. Qualquer alteração feita apenas dentro de node_modules será perdida com a exclusão.

  1. Na raiz do projeto, execute pwd e du -sh ./node_modules; anote também o espaço livre do macOS.
  2. Confira o package.json, o lockfile correto, a configuração do workspace e as alterações locais (git status); se um projeto legado tiver só o npm-shrinkwrap.json, renomeie-o para package-lock.json antes de usar o npm v12, sem sobrescrever um arquivo existente.
  3. Verifique o acesso a registries privados, dependências Git e file:, pacotes locais, downloads externos e ferramentas de compilação; encerre servidores de desenvolvimento, watchers e qualquer processo que use node_modules.
  4. Mova para o Lixo apenas a pasta node_modules confirmada e reinstale a partir da raiz correta, com o gerenciador e o lockfile definidos pelo repositório.
  5. Execute o build, os testes, o lint e o app; meça de novo o espaço e só então esvazie o Lixo.

Não use node_modules como única cópia de um pacote ou de uma correção manual. Se uma dependência exata não puder mais ser baixada e não estiver arquivada em outro lugar, apagá-la pode inutilizar um projeto antigo.

Remova uma única pasta de dependências confirmada

No projeto confirmado, mova apenas a pasta node_modules para o Lixo pelo Finder — nunca o repositório que a contém. No Terminal, rm -rf ./node_modules não passa pelo Lixo e é irreversível: antes, confirme de novo a raiz com pwd e nunca monte o comando com curingas, variáveis vazias ou saída do find que você não conferiu. Reinstale a partir dessa raiz com npm ci quando o package-lock.json for a referência oficial, ou use o fluxo de lockfile imutável definido pelo repositório para pnpm, Yarn ou Bun. Trate um monorepo como um único sistema, governado pelo lockfile da raiz.

Reinstale e valide o projeto inteiro

Uma instalação concluída, sozinha, não prova que o projeto voltou a funcionar. Execute os comandos documentados de build, teste, lint e inicialização: módulos nativos e scripts de ciclo de vida ainda podem falhar depois de uma mudança de toolchain. A reinstalação custa downloads, descompactação, links e talvez compilação; numa conexão lenta ou limitada, comece por clones inativos e mantenha as dependências dos projetos críticos. Se algo falhar, restaure a pasta a partir do Lixo e diagnostique credenciais, rede, versões e lockfile antes de limpar outro projeto.

Limites de exclusão e custo de recuperação

Encontre pastas node_modules grandes, proteja o código-fonte e o lockfile, remova as dependências projeto por projeto e reinstale com npm, pnpm, Yarn ou Bun.

Item ou açãoOnde verificarConsequência
Separe node_modules do projeto e do cacheprojeto/node_modulesA pasta node_modules contém a árvore de dependências instalada de um projeto e só pode ser reconstruída enquanto todos os insumos continuarem disponíveis.
Confirme que as dependências podem ser reconstruídaspackage.json + lockfile + configuração do workspaceUm lockfile torna a reinstalação mais previsível, mas não é uma cópia dos pacotes.
Remova uma única pasta de dependências confirmadaLixo / reinstalação pelo gerenciador de pacotesNo projeto confirmado, mova apenas a pasta node_modules para o Lixo pelo Finder — nunca o repositório que a contém.
Reinstale e valide o projeto inteirobuild + testes + inicialização do appUma instalação concluída, sozinha, não prova que o projeto voltou a funcionar.

Perguntas frequentes

É seguro apagar node_modules no Mac?

Em geral, sim, se você preservar o package.json, o lockfile correto, os arquivos do workspace, o código-fonte e o acesso a todas as fontes das dependências. O projeto não funciona até a reinstalação terminar. Mova para o Lixo uma pasta verificada, reinstale e teste, e só esvazie o Lixo quando o projeto estiver funcionando.

Devo apagar o package-lock.json junto com node_modules?

Não. O package-lock.json registra a resolução de dependências do npm e é a base do npm ci; mantenha-o junto com o package.json. Apagá-lo pode forçar uma nova resolução, com outras versões transitivas. O npm v12 ignora o npm-shrinkwrap.json; se esse for o único lockfile de um projeto legado, renomeie-o para package-lock.json, sem sobrescrever um arquivo existente.

node_modules e o cache do npm são a mesma coisa?

Não. A pasta node_modules é a árvore de dependências instalada de um projeto; o cache compartilhado do npm costuma ficar em ~/.npm. Apagar uma categoria não remove a outra.

Fontes

Mais guias de armazenamento para desenvolvedores