node_modules por toda parte: como encontrar, limpar e recuperar

Uma pasta node_modules guarda as dependências instaladas para um projeto JavaScript ou TypeScript, e uma pasta típica tem algumas centenas de megabytes. Com dezenas de projetos antigos, elas chegam facilmente a dezenas de gigabytes. Elas podem ser apagadas com segurança desde que você guarde o package.json e o lockfile: o gerenciador de pacotes reinstala as mesmas versões quando você voltar ao projeto.

Encontre todas as pastas node_modules e o tamanho delas

Este comando pesquisa a sua pasta pessoal, ignora ~/Library e o Lixo e mostra cada pasta node_modules com o tamanho, com as maiores no fim:

find ~ \( -path "$HOME/Library" -o -path "$HOME/.Trash" \) -prune -o -type d -name node_modules -prune -print0 2>/dev/null | xargs -0 du -sh 2>/dev/null | sort -h

Como funciona: o primeiro -prune ignora as duas pastas excluídas, -type d -name node_modules encontra as pastas, e o segundo -prune impede o find de descer nelas, então as node_modules aninhadas são contadas uma vez só, dentro da pasta-mãe. O du -sh mede cada uma e o sort -h ordena a lista. O comando só lê. Numa pasta pessoal grande, pode levar alguns minutos, e o Terminal pode pedir acesso a Documentos, Mesa ou Downloads.

Ignore os resultados dentro de pastas de ferramentas como ~/.nvm, ~/.vscode ou ~/.cursor. Eles pertencem a ferramentas instaladas e extensões de editores, e não aos seus projetos.

Se os seus projetos usam o pnpm, os tamanhos mostrados são maiores do que o espaço que você vai recuperar. O motivo é explicado mais abaixo.

Apague as que você não precisa

Antes de apagar, abra a pasta do projeto e confira se ela tem um lockfile: package-lock.json (npm), pnpm-lock.yaml (pnpm), yarn.lock (Yarn) ou bun.lock / bun.lockb (Bun). Guarde esse arquivo e o package.json.

A forma mais segura de apagar é arrastar a node_modules para o Lixo no Finder. Você ainda pode mudar de ideia até esvaziar o Lixo. Com muitos arquivos pequenos, mover para o Lixo leva um instante.

No Terminal, dentro da pasta de um projeto:

cd ~/Projects/old-app
rm -rf node_modules

O rm -rf apaga de forma definitiva, sem passar pelo Lixo. Confira antes em que pasta você está com pwd e nunca o execute com um curinga ou com uma variável vazia.

npkill: uma alternativa interativa

O npkill lista as pastas node_modules com o tamanho de cada uma e permite apagá-las com uma tecla de cada vez:

npx npkill -d ~/Projects

O -d define onde a pesquisa começa; sem ele, o npkill começa na pasta atual. Navegue com as setas e pressione Espaço ou Del para apagar a pasta selecionada. O npkill apaga na hora, sem passar pelo Lixo. Ele marca com ⚠️ as pastas de que apps precisam para funcionar, e essas devem ficar onde estão. O --dry-run simula a exclusão, se quiser testar antes.

Reinstale quando voltar a um projeto

Use o comando que instala exatamente o que o lockfile indica:

O npm ci exige um lockfile, remove antes qualquer node_modules existente e nunca altera o package.json nem o lockfile. Um npm install simples também funciona, mas pode atualizar o lockfile.

Outras pastas que se recriam sozinhas

Frameworks e ferramentas de build guardam caches e saídas ao lado da node_modules. Elas podem ser apagadas com segurança em projetos que você não está rodando; o próximo build ou servidor de desenvolvimento as recria.

dist e build também costumam ser saídas de build, mas os nomes são genéricos. Alguns projetos versionam arquivos nelas ou as usam para outra coisa, então olhe o conteúdo antes de apagar.

Para listar os caches de frameworks numa pasta de projetos:

find ~/Projects -type d \( -name .next -o -name .nuxt -o -name .svelte-kit -o -name .turbo -o -name .parcel-cache \) -prune -print0 | xargs -0 du -sh | sort -h

Limpe os caches globais de pacotes

Cada gerenciador de pacotes também mantém um cache de downloads compartilhado por todos os projetos. Limpá-lo é definitivo, mas inofensivo: os pacotes são baixados de novo quando necessário.

npm cache clean --force
pnpm store prune
yarn cache clean
bun pm cache rm

• O npm guarda o cache em ~/.npm/_cacache. A documentação do cache do npm explica por que o clean exige --force e observa que o npm cache verify faz a coleta de lixo sem esvaziar tudo. Os pacotes baixados pelo npx ficam em ~/.npm/_npx.
• O pnpm guarda o store em ~/Library/pnpm/store no macOS (pnpm store path mostra o seu). O pnpm store prune remove só os pacotes que nenhum projeto referencia, e a documentação do pnpm sugere executá-lo de vez em quando, e não o tempo todo.
• O Yarn Classic usa o cache em ~/Library/Caches/Yarn. No Yarn Berry, yarn cache clean --mirror esvazia o cache global em ~/.yarn/berry/cache.
• O Bun usa o cache em ~/.bun/install/cache; bun pm cache rm o esvazia.

Versões antigas do Node.js instaladas com o nvm também se acumulam em ~/.nvm/versions/node; nvm uninstall <version> remove uma de que você não precisa mais.

Por que o pnpm libera menos do que o du indica

O npm e o Yarn Classic copiam cada pacote para a node_modules de cada projeto. O pnpm guarda cada pacote uma única vez, num store endereçável por conteúdo, e liga os arquivos dele a cada projeto que o usa. No macOS, o packageImportMethod padrão do pnpm tenta primeiro clones APFS e depois links físicos.

Em qualquer dos casos, os bytes são compartilhados. O du continua contando o tamanho inteiro em cada projeto, então apagar a node_modules de um projeto pnpm normalmente libera bem menos do que o valor informado. O espaço volta quando o pnpm store prune remove os pacotes que nenhum dos projetos restantes usa. Para isso funcionar, o store precisa estar no mesmo disco que o projeto; projetos num disco externo têm um store próprio lá.

Como o MoreRoom ajuda

A versão gratuita do MoreRoom encontra pastas node_modules em projetos que têm um lockfile e não foram mexidos há 30 dias, além de caches de frameworks como .next e .turbo, e as marca como “Seguro remover”. Ela ignora ~/Library e pastas de ferramentas como ~/.nvm e ~/.vscode. Você move os itens para o Lixo um de cada vez, com Desfazer. Para o cache do npm e o store do pnpm, o MoreRoom executa npm cache clean --force e pnpm store prune; esses comandos são definitivos e estão sinalizados como tal.

O MoreRoom Pro acrescenta a Hibernação de projetos: os projetos inativos se desfazem das pastas recriáveis, como a node_modules e as saídas de build, e despertam de novo com um clique quando você volta a eles. O Pro também inclui o Coletor e o modo meta.