Corrigir 'sh: command not found: npm' no macOS e Linux

Quando você encontra sh: command not found: npm no seu terminal, significa que seu shell não consegue localizar o executável do npm. Este erro normalmente aparece quando o Node.js não está instalado, o npm está ausente do PATH do seu sistema, ou a configuração do seu shell precisa ser atualizada. Veja como diagnosticar e corrigir este problema comum de troubleshooting do Node.js em sistemas macOS e Linux.

Entendendo o Erro de PATH do npm

O erro ocorre porque seu shell procura por comandos nos diretórios listados na variável de ambiente PATH. Quando o npm não está em nenhum desses diretórios, você recebe a mensagem sh: command not found: npm. Isso acontece em três cenários: o Node.js nunca foi instalado, a instalação falhou parcialmente, ou sua configuração de PATH está incorreta.

Diagnóstico Rápido: Verifique Sua Configuração Atual

Primeiro, verifique se o Node.js está instalado:

node --version

Se o Node.js está instalado mas o npm não está funcionando, verifique se o npm existe no seu sistema:

which npm

Nenhuma saída significa que o npm não está no seu PATH. Em seguida, examine sua configuração atual de PATH:

echo $PATH

Isso mostra todos os diretórios que seu shell procura por comandos. Se o diretório do npm não estiver listado, esse é o seu problema.

Instalando Node.js e npm no macOS

Usando Homebrew (Recomendado)

O Homebrew fornece o método de instalação mais limpo para macOS:

brew install node

Isso instala tanto o Node.js quanto o npm, configurando automaticamente seu PATH. Verifique a instalação:

npm --version

Método de Download Direto

Alternativamente, baixe o instalador do nodejs.org. O instalador do macOS lida com a configuração do PATH automaticamente, mas você precisará reiniciar seu terminal depois.

Instalando Node.js e npm no Linux

Sistemas Ubuntu/Debian

Use o gerenciador de pacotes da sua distribuição:

sudo apt update
sudo apt install nodejs npm

Sistemas Fedora/RHEL

sudo dnf install nodejs npm

Arch Linux

sudo pacman -S nodejs npm

Após a instalação, verifique se o npm funciona:

npm --version

Corrigindo Problemas de Configuração do PATH

Se o npm está instalado mas ainda mostra o erro, você precisa adicioná-lo ao seu PATH manualmente.

Para Usuários do Bash

Edite seu arquivo .bashrc:

echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc
source ~/.bashrc

Para Usuários do Zsh (Padrão do macOS)

Edite seu arquivo .zshrc:

echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.zshrc
source ~/.zshrc

Substitua /usr/local/bin pelo caminho real da instalação do npm. Encontre-o usando:

find / -name npm 2>/dev/null

Usando o Node Version Manager (nvm)

O nvm previne conflitos de versão e problemas de PATH ao gerenciar instalações do Node.js separadamente dos pacotes do sistema. Esta abordagem elimina a maioria dos erros “npm command not found”.

Instalar o nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Instalar Node.js via nvm

nvm install node
nvm use node

O nvm lida automaticamente com a configuração do PATH e permite alternar entre versões do Node.js para diferentes projetos. É particularmente útil ao trabalhar com projetos que requerem versões específicas do Node.js.

Troubleshooting Específico por Shell

Diferentes shells podem requerer configurações específicas:

• Bash: Verifique .bashrc ou .bash_profile
• Zsh: Verifique .zshrc
• Fish: Verifique ~/.config/fish/config.fish

Sempre reinicie seu terminal ou execute source no arquivo de configuração após fazer alterações.

Verificando Sua Correção

Após aplicar qualquer solução, verifique se o npm funciona corretamente:

npm --version
npm list -g --depth=0

Teste instalando um pacote para garantir funcionalidade completa:

npm install -g npm@latest

Armadilhas Comuns a Evitar

Não use sudo com instalações globais do npm a menos que seja absolutamente necessário—isso pode causar problemas de permissão posteriormente. Se você encontrar erros de permissão, considere mudar o diretório padrão do npm ou usar o npx em vez de instalações globais.

Para ambientes corporativos com proxies, configure as definições de proxy do npm:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

Conclusão

O erro sh: command not found: npm é simples de corrigir uma vez que você entende sua causa. Seja através de gerenciadores de pacotes, instalação direta ou nvm, fazer o npm funcionar envolve garantir que o Node.js está instalado e seu PATH está configurado corretamente. Usar o nvm fornece a solução mais flexível, especialmente para desenvolvedores gerenciando múltiplos projetos. Com o npm funcionando adequadamente, você pode focar em construir ao invés de fazer troubleshooting do seu ambiente de desenvolvimento.

Perguntas Frequentes

Por que o npm funciona em um terminal mas não em outro?

Diferentes terminais podem usar diferentes configurações de shell. Verifique qual shell você está usando com echo $SHELL e garanta que o PATH está definido no arquivo de configuração correto para aquele shell.

Posso ter múltiplas versões do npm instaladas no mesmo sistema?

Sim, usar o nvm permite que você instale e alterne entre múltiplas versões do Node.js e npm. Cada versão é isolada, prevenindo conflitos entre projetos que requerem versões diferentes.

Devo instalar pacotes npm globalmente ou localmente?

Instale pacotes localmente para dependências de projeto e globalmente apenas para ferramentas de linha de comando que você usa em todos os projetos. Instalação local previne conflitos de versão e problemas de permissão.

Como corrigir erros de permissão do npm sem usar sudo?

Mude o diretório padrão do npm para um que você possui usando npm config set prefix ou use npx para executar pacotes sem instalá-los globalmente. Isso evita problemas de permissão completamente.