Se o cache do npm e pastas node_modules antigas estão ocupando espaço no teu Mac, primeiro separa o cache compartilhado do npm das dependências locais dos projetos. Revise o cache antes de limpá-lo e depois apague pastas node_modules obsoletas apenas quando estiveres pronto para reinstalar ou quando não precisares mais daquele projeto intacto.
Essa distinção é importante porque o npm cache e o node_modules resolvem problemas diferentes. Eles também têm consequências de limpeza diferentes.
Um é um cache de pacotes reutilizável. O outro é a árvore de dependências contra a qual teu projeto realmente roda. Tratá-los como um único bloco descartável é a forma como desenvolvedores recuperam espaço rapidamente e depois perdem tempo reconstruindo o ambiente errado.
Regra principal: Limpe o cache compartilhado para ganhar espaço. Remova node_modules apenas quando o custo de rebuild do projeto for aceitável.
Resposta rápida
- Verifica se o problema real é
~/.npm,node_modulesnos projetos, ou ambos. - Use
npm cache verifyantes de pular para uma limpeza completa do cache. - Use
npm cache clean --forceapenas quando recuperar espaço em disco valer o custo de re-download. - Apague
node_modulesapenas em projetos que podes reinstalar com segurança ou que não precisas mais ativamente. - Revise repositórios antigos, branches arquivadas e demos abandonadas antes de tocar em workspaces ativos.
- Se o npm é apenas uma parte do problema, revise o armazenamento de desenvolvedor por ecossistema em vez de apenas pelo tamanho da pasta.
node_modules locais dos projetos parecem semelhantes em pressão de tamanho, mas não são a mesma decisão de limpeza.
Por que o cache do npm e node_modules crescem tão rápido no Mac
Máquinas de desenvolvedores JavaScript raramente crescem de um projeto só. O padrão real é acumulação.
Tu instalas pacotes em múltiplos apps, branches, protótipos e repositórios de clientes. O npm mantém um cache reutilizável para que as instalações não precisem buscar tudo do zero toda vez. Cada projeto também mantém sua própria árvore de dependências local em node_modules.
Isso significa que o crescimento do disco pode vir de duas direções ao mesmo tempo:
- um cache compartilhado do npm que continua expandindo conforme instalas novos pacotes e versões;
- múltiplas pastas de projetos, cada uma com sua própria árvore
node_modules; - dependências duplicadas ou quase duplicadas entre repositórios antigos;
- módulos nativos e pacotes de toolchain que adicionam custo de rebuild mesmo quando são tecnicamente descartáveis;
- projetos parados que nunca foram arquivados, apagados ou reinstalados de forma limpa.
O resultado é familiar: um repositório é irritante, dez repositórios são caros, e um ano de trabalho normal se transforma em um problema silencioso de armazenamento.
Cache do npm vs node_modules: Qual é a diferença?
Essa é a distinção que mais importa.
De acordo com a documentação oficial do npm, os arquivos de cache ficam em ~/.npm em sistemas Posix por padrão, enquanto as instalações locais vão para ./node_modules sob a raiz do pacote atual. O npm carrega pacotes no cache primeiro e depois os descompacta em node_modules para o projeto que precisa deles.
| Item | Localização típica no Mac | Para que serve | Seguro por padrão? | Principal consequência da limpeza |
|---|---|---|---|---|
| Cache do npm | ~/.npm | Cache compartilhado de download de pacotes usado pelo npm | Geralmente sim, se o objetivo é recuperar espaço em disco | Instalações futuras podem precisar baixar pacotes novamente |
| node_modules | project-root/node_modules | A árvore de dependências instalada para um projeto específico | Depende do contexto | O projeto precisará de reinstalação, rebuild ou re-link antes de rodar normalmente |
É por isso que “o npm está ocupando espaço” geralmente é vago demais para ser acionável. Precisas saber se a pressão vem do cache compartilhado, de instalações antigas de projetos, ou de ambos.
O que a própria documentação do npm implica
O cache do npm é projetado como um cache, não como a árvore de dependências funcional do teu projeto. O npm documenta explicitamente que é um cache que pode ser repopulado depois.
node_modules é diferente. Essa pasta é onde os pacotes do teu projeto, executáveis e o grafo de dependências local realmente vivem. Se a removeres, não estás apenas limpando um cache. Estás removendo as dependências instaladas que o projeto usa atualmente.
É seguro apagar o cache do npm no Mac?
Geralmente sim, mas o motivo importa.
A documentação oficial do npm diz que o cache é verificado por integridade e que limpá-lo geralmente só deve ser necessário quando o objetivo é recuperar espaço em disco. Essa é uma diferença de enquadramento importante. O cache do npm não deve ser tratado como estado precioso, mas também não é algo que precisas limpar rotineiramente apenas porque existe.
O modelo mental seguro é:
- se teu Mac está apertado em espaço, a limpeza do cache pode ser uma troca razoável;
- se tuas instalações estão funcionando normalmente, limpar o cache é frequentemente desnecessário;
- se limpares, espera que instalações posteriores baixem pacotes novamente;
- se apenas queres verificar o estado do cache primeiro, usa
npm cache verify.
Melhor primeiro passo: verificar antes de limpar
O npm documenta npm cache verify como o passo de verificação offline para os conteúdos existentes do cache. Isso o torna o melhor primeiro comando quando queres uma verificação de menor risco antes de recuperar espaço.
npm cache verifySe teu objetivo é especificamente liberar espaço em disco, o comando documentado de limpeza do npm é:
npm cache clean --forceA flag --force é exigida por design. O npm trata a limpeza do cache como uma decisão intencional de espaço em disco, não como um hábito de manutenção diário.
É seguro apagar node_modules no Mac?
Às vezes, mas é aqui que o contexto importa muito mais.
Apagar node_modules remove a árvore de dependências local daquele projeto. Se o projeto está ativo, a consequência imediata geralmente é óbvia: scripts param de encontrar pacotes, binários locais desaparecem de node_modules/.bin, e a próxima instalação ou build pode demorar mais do que gostarias.
Isso não significa que nunca deves removê-lo. Significa que deves removê-lo de forma deliberada.
Bons candidatos para apagar node_modules:
- um projeto antigo que não rodas mais ativamente;
- uma demo ou protótipo parado que podes reconstruir depois;
- um repositório que vais reinstalar de forma limpa de qualquer forma;
- um projeto com um lockfile confiável onde a reinstalação é esperada e aceitável.
Situações de maior atrito:
- um repositório de trabalho ativo logo antes de um prazo, demo ou build de release;
- um projeto com módulos nativos que demoram para reconstruir;
- um workspace que não tocaste há meses e podes não lembrar como restaurar rapidamente;
- um repositório sem uma história de dependências limpa ou sem o lockfile que esperas.
Regra de limpeza de projetos: apagar node_modules é um reset do workspace, não uma poda de cache inofensiva.
Por que pastas node_modules antigas doem tanto
Um projeto pode ser gerenciável. O verdadeiro desperdício vem de ter muitos deles.
Cada repositório antigo pode manter uma árvore de dependências completa, metadados do gerenciador de pacotes, pacotes nativos opcionais, toolchains de framework e artefatos específicos de versão. É por isso que desenvolvedores frequentemente pensam que o npm é o problema quando o maior ofensor é na verdade uma pilha de pastas node_modules esquecidas entre repositórios abandonados.
Como limpar o cache do npm manualmente
Se quiseres o caminho manual, mantém-te estreito e explícito.
1. Verifica o diretório de cache ativo
Se alteraste a configuração do npm em algum momento, teu cache pode não estar na localização padrão. Pergunta ao npm primeiro:
npm config get cache2. Verifica o cache antes de apagá-lo
Usa o passo de verificação documentado primeiro:
npm cache verify3. Limpe o cache apenas se realmente quiseres o espaço de volta
Se recuperar espaço em disco valer os re-downloads posteriores:
npm cache clean --force4. Verifica o tamanho novamente se necessário
Uma vez que saibas o caminho do cache, podes inspecionar seu tamanho diretamente:
du -sh "$(npm config get cache)"Essa é a sequência mais segura porque separa localização, verificação e limpeza em decisões distintas.
Como encontrar pastas node_modules antigas antes de apagar qualquer coisa
Essa geralmente é a limpeza de maior valor.
Começa pelos projetos que não buildas mais ativamente. Isso importa mais do que caçar a maior pasta no Finder sem contexto.
Usa uma ordem de revisão como esta:
- Busca no teu diretório principal de projetos por pastas
node_modules. - Verifica quais repositórios estão parados, arquivados ou fáceis de reinstalar.
- Confirma se o projeto ainda precisa rodar localmente esta semana.
- Apaga apenas as pastas
node_modulescujo custo de rebuild entendas.
Se quiseres uma revisão assistida pelo Terminal, usa comandos que te mostrem onde essas pastas realmente estão antes de apagar qualquer coisa:
find ~/Projects -type d -name node_modules -prune -print
find ~/Projects -type d -name node_modules -prune -exec du -sh {} +Isso ainda é manual, mas é melhor do que reagir emocionalmente a uma pasta de trabalho enorme.
O que revisar antes de apagar o node_modules de um projeto
- O repositório ainda está ativo?
- Tens o lockfile que esperas?
- Há módulos nativos ou passos de codegen que tornam a reinstalação mais lenta?
- O projeto faz parte de um monorepo ou workspace que não queres perturbar casualmente?
- Arquivar ou apagar o projeto inteiro aposentado seria uma limpeza melhor do que apenas remover
node_modules?
Frequentemente, a ação de limpeza mais forte não é “limpar dependências em todo lugar”. É “apagar o projeto antigo que não precisas mais.”
E os caches do yarn, pnpm e bun?
Mantém esta parte separada do npm.
Se o projeto usa outro gerenciador de pacotes, usa o próprio modelo de limpeza desse gerenciador em vez de assumir que comandos do npm se aplicam diretamente.
Yarn
O Yarn moderno documenta yarn cache clean como o comando que remove arquivos de cache compartilhado. Ele também expõe --mirror e --all para escopos de limpeza mais amplos.
yarn cache cleanpnpm
O pnpm usa um modelo de store em vez do padrão exato de cache do npm. A documentação oficial do pnpm descreve pnpm store prune como removendo pacotes não referenciados do store e nota que instalações futuras podem baixar os pacotes removidos novamente quando necessário.
pnpm store pruneBun
O Bun documenta um cache global de pacotes em ~/.bun/install/cache por padrão. Sua documentação também nota que pacotes ainda são copiados para node_modules após o download, então o Bun pode criar a mesma confusão de “cache mais instalação de projeto” se olhares apenas para o tamanho da pasta.
O importante não é memorizar cada comando. É evitar misturar modelos de armazenamento. Cache do npm, cache do Yarn, store do pnpm e cache do Bun são problemas relacionados, não idênticos.
Por que a limpeza de desenvolvedor é mais segura quando revisas por ecossistema
node_modules raramente é o único problema de armazenamento de desenvolvedor em um Mac. Geralmente fica ao lado de dados do Xcode, armazenamento de simulador, imagens do Docker, build cache, logs e outros caminhos específicos de toolchain.
Um navegador de arquivos simples mostra que uma pasta é grande. Não te diz se é:
- um cache do npm reconstrutível;
- uma árvore de dependências de workspace ativo;
- um store do pnpm;
- um cache do Docker;
- ou um ecossistema diferente que simplesmente acontece de viver perto dos teus projetos.
É por isso que a limpeza de desenvolvedor funciona melhor quando o fluxo de trabalho permanece consciente do ecossistema.
Se tua situação real é “npm mais Docker mais dados antigos do Xcode mais repositórios parados demais”, esse modelo mais amplo de revisão-primeiro é mais útil do que caçar uma pasta de cada vez.
Conclusão
Se o cache do npm e node_modules estão ocupando espaço no teu Mac, não os trates como o mesmo alvo de limpeza.
Usa npm cache verify e, quando recuperar espaço for o objetivo real, npm cache clean --force para o cache compartilhado. Revise pastas node_modules antigas projeto por projeto e apague-as apenas quando entenderes o custo de reinstalação.
Esse é o caminho mais seguro: separa cache de estado do workspace, revisa projetos parados antes dos ativos e mantém a limpeza de desenvolvedor ligada ao contexto do ecossistema em vez de exclusão cega de pastas.
Perguntas frequentes
O que é o cache do npm no Mac?
O cache do npm é o cache local de download de pacotes que o npm mantém no teu Mac, geralmente em ~/.npm, a menos que tu tenhas alterado a configuração de cache. Ele é diferente das dependências de projeto armazenadas em node_modules.
É seguro apagar o cache do npm no Mac?
Geralmente sim, se teu objetivo é recuperar espaço em disco. A própria documentação do npm posiciona o cache como reconstruível e recomenda limpá-lo apenas quando a recuperação de espaço é o motivo real, pois instalações futuras podem baixar os pacotes novamente.
É seguro apagar o node_modules no Mac?
Depende do contexto. Apagar o node_modules remove as dependências instaladas daquele projeto, então tu deves fazer isso apenas quando estiveres pronto para reinstalar ou quando o projeto estiver parado o suficiente para que o custo de rebuild não importe.
Por que pastas node_modules antigas ocupam tanto espaço?
Cada projeto pode manter sua própria árvore de dependências, pacotes de build, módulos nativos e artefatos específicos de versão. Entre muitos repositórios, essa pegada de instalação local duplicada acumula rapidamente.
Qual é a diferença entre o cache do npm e o node_modules?
O cache do npm é o cache compartilhado de downloads do npm, enquanto o node_modules é a pasta de dependências local do projeto contra a qual teu app realmente roda. Um é um cache reutilizável; o outro é a árvore de dependências instalada para um projeto específico.