Como limpar o cache do npm no Mac com segurança
Equipe AskClean · Atualizado 2026-11-02
Localize o cache ativo com npm config get cache, meça esse caminho com du e execute npm cache verify antes de apagar qualquer coisa. Use npm cache clean --force só quando precisar de fato do espaço e aceitar baixar os pacotes de novo no futuro. Isso não remove node_modules, o package.json nem o seu lockfile.
Separe cache, dependências instaladas e projeto
O cache do npm guarda downloads reutilizáveis por vários projetos e costuma ficar em ~/.npm no macOS, embora possa ser configurado em outro lugar. A pasta node_modules é a árvore de dependências instalada de um projeto. O package.json e o package-lock.json registram o estado do projeto e não são cache. O npm-shrinkwrap.json também não é cache, mas o npm v12 não lê mais esse arquivo: se ele for o único lockfile de um projeto legado, renomeie-o para package-lock.json, que tem o mesmo formato, antes de reinstalar — e nunca sobrescreva um package-lock.json existente.
Meça o cache ativo e verifique-o primeiro
Não presuma que uma pasta ~/.npm existente seja o cache ativo. O comando npm config get cache mostra o caminho usado pela configuração atual; meça-o com du e anote o espaço livre. O npm cache verify confere o índice e os dados, valida a integridade e remove o conteúdo desnecessário sem descartar os downloads válidos. Para a manutenção de rotina, essa verificação costuma bastar; se o objetivo era resolver uma falha de instalação, repita o comando original uma vez e compare o erro exato.
- Execute npm --version e npm config get cache; confirme que o caminho retornado é um cache, não uma pasta de projeto.
- Meça esse caminho exato com du -sh e anote o espaço livre do macOS, sem alterar o package.json nem os lockfiles.
- Encerre os processos npm install, npm ci, npm exec e de publicação; execute npm cache verify e guarde o resumo e eventuais erros.
- Execute npm cache clean --force só se a verificação não bastar, a economia de espaço for relevante e todos os artefatos necessários continuarem acessíveis.
- Execute de novo npm cache verify, meça o mesmo caminho e teste um projeto representativo com o lockfile, o build e os testes inalterados.
Nunca passe um caminho não verificado para rm -rf. Também não combine a limpeza do cache com apagar ou regenerar um lockfile: você mudaria duas variáveis de uma vez e perderia a comparação necessária para diagnosticar o problema.
Use npm cache clean --force só quando fizer sentido
Execute npm cache clean --force apenas quando o cache medido for grande, você precisar do espaço agora e puder baixar os artefatos outra vez. O comando limpa o cache configurado, não node_modules nem os lockfiles. Depois disso, npm install e npm ci podem demorar mais ou falhar sem conexão; registries privados, servidores Git, proxies e pacotes que deixaram de estar disponíveis aumentam o custo de recuperação. Use --force só nesse comando e não defina force como configuração permanente do npm.
Valide o resultado sem mudar as dependências
Depois da limpeza, consulte de novo o caminho, meça o mesmo local e compare o espaço livre real do macOS. Teste um projeto representativo, com o package.json e o lockfile inalterados, rodando o build e os testes dele. Se o erro original voltar, não repita a exclusão: ERESOLVE, credenciais, erros 404, proxies, certificados, engines do Node.js, builds nativos e scripts de ciclo de vida exigem outro diagnóstico. O AskClean reconhece apenas o ~/.npm padrão, como um único item de cache, e os itens confirmados são excluídos permanentemente; se o cache foi personalizado, confirme o caminho com npm config get cache.
Limites de exclusão e custo de recuperação
Localize e meça o cache do npm no Mac, execute antes npm cache verify e use npm cache clean --force só se precisar, sem tocar em node_modules nem no lockfile.
| Item ou ação | Onde verificar | Consequência |
|---|---|---|
| Separe cache, dependências instaladas e projeto | npm config get cache | O cache do npm guarda downloads reutilizáveis por vários projetos e costuma ficar em ~/.npm no macOS, embora possa ser configurado em outro lugar. |
| Meça o cache ativo e verifique-o primeiro | npm cache verify | Não presuma que uma pasta ~/.npm existente seja o cache ativo. |
| Use npm cache clean --force só quando fizer sentido | npm cache clean --force | Execute npm cache clean --force apenas quando o cache medido for grande, você precisar do espaço agora e puder baixar os artefatos outra vez. |
| Valide o resultado sem mudar as dependências | instalação + verificação offline/registry privado | Depois da limpeza, consulte de novo o caminho, meça o mesmo local e compare o espaço livre real do macOS. |
Perguntas frequentes
É seguro executar npm cache clean --force no Mac?
Para o código-fonte e os arquivos do projeto, sim, desde que o npm aponte para o cache correto — mas o comando descarta downloads reutilizáveis. Meça e verifique primeiro, encerre os processos ativos e conte com a necessidade de rede nas próximas instalações. Não use um comando de exclusão recursiva montado à mão.
Devo executar npm cache verify ou npm cache clean primeiro?
Primeiro, npm cache verify. Ele verifica a integridade e remove dados desnecessários mantendo o conteúdo válido; o clean --force fica reservado a uma necessidade de espaço medida ou a um problema de cache confirmado que a verificação não resolveu.
Limpar o cache do npm apaga o package-lock.json?
Não. O package.json e o package-lock.json são arquivos do projeto, não cache. 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 nem alterar a resolução de dependências durante a limpeza do cache.
Fontes