Índice
Você instalou o Claude Code, mas digitar claude no terminal devolve isto — soa familiar?
zsh: command not found: claude
bash: claude: command not found
'claude' is not recognized as an internal or external command # WindowsEste erro significa "o executável claude não pode ser encontrado", e a causa costuma ser "a pasta de instalação não está no seu PATH." A instalação em si muitas vezes deu certo — o shell apenas não sabe onde procurar. Este artigo cobre métodos e locais de instalação, como corrigir o PATH, conflitos entre múltiplas instalações, armadilhas específicas do Windows e atualização — com base em informações oficiais.
Pontos-chave logo de cara. (1) command not found quase sempre é só "~/.local/bin (o diretório de instalação) não está no PATH" — adicione-o e reinicie o terminal e funciona. (2) Um erro de permissão do npm (EACCES) NÃO deve ser resolvido com sudo — em vez disso, mude para o instalador nativo. (3) Quando travar, execute claude doctor — ele verifica a saúde da instalação, as configurações e o resultado da atualização de uma só vez. Os comandos exatos e os padrões mudam conforme a versão, então confirme os mais recentes na documentação oficial.
Instalado, mas não encontrado
— o diretório de instalação só não está no PATH
O binário existe sim. O PATH do shell apenas não lista a localização dele.
Então a correção é "adicionar uma linha ao PATH" — geralmente em menos de um minuto.
1. O que este erro está dizendo
Quando você digita um comando, o shell (zsh / bash / PowerShell) procura, em ordem, nas pastas listadas na variável de ambiente PATH e executa o primeiro executável correspondente. command not found: claude significa que nenhuma dessas pastas continha claude.
O importante: isso não significa necessariamente que a instalação falhou. O instalador nativo coloca claude em ~/.local/bin (Windows: %USERPROFILE%\.local\bin), mas se essa pasta não estiver no PATH, o binário existe e mesmo assim o shell não consegue encontrá-lo. Por isso a maioria dos casos se resolve com "adicionar uma linha ao PATH e reiniciar o terminal." Antes de suspeitar de uma instalação que falhou, execute ls ~/.local/bin/claude para verificar se o binário está lá.
No Windows, usar o "shell errado" para o comando de instalação (por exemplo, rodar o comando do PowerShell no CMD) produz erros diferentes — abordados na §4. Primeiro, vamos fixar os métodos e locais de instalação corretos.
2. Métodos de instalação e onde o binário fica
Aqui estão os principais métodos de instalação a partir de 2026 e onde o binário acaba (o instalador nativo é o recomendado).
| Método | Comando (formato) | Local / observação |
|---|---|---|
| Nativo (recomendado) mac/Linux | curl -fsSL https://claude.ai/install.sh | bash | ~/.local/bin/claude. Atualiza automaticamente |
| Nativo (recomendado) Windows | No PowerShell: irm https://claude.ai/install.ps1 | iex | %USERPROFILE%\.local\bin\claude.exe |
| npm | npm install -g @anthropic-ai/claude-code | Requer Node 18+. Instala o mesmo binário nativo |
| Homebrew (mac) | brew install --cask claude-code | Sem atualização automática → brew upgrade |
| WinGet (Windows) | winget install Anthropic.ClaudeCode | Sem atualização automática → winget upgrade |
O ponto: o instalador nativo é oficialmente recomendado. A versão npm instala o mesmo binário nativo (o Node 18+ é necessário apenas no momento da instalação; o binário não precisa do Node para rodar), mas é mais propensa a problemas de permissão e de PATH. Se você está instalando do zero, o nativo é a escolha segura. Observe que instalar apenas a extensão do VS Code embute um CLI privado dentro da extensão e NÃO adiciona claude ao PATH — se você quer claude no terminal, instale-o separadamente.
3. Principais causas e correções
Aqui estão as causas comuns em torno de command not found, junto com as correções.
Principais causas de instalação / PATH
~/.local/bin está fora do PATH. Adicione export PATH="$HOME/.local/bin:$PATH" ao ~/.zshrc/~/.bashrc e reinicie o terminal.sudo npm (oficialmente desencorajado). Mudar para o instalador nativo é a correção mais rápida e segura.which -a claude (Win: where.exe claude) e mantenha apenas o nativo.Could not find native binary package ... aparece quando você instalou com as dependências opcionais ignoradas. Reinstale sem --omit=optional etc.
Na dúvida, "reinstalar pelo instalador nativo" resolve a maioria desses casos —
ele contorna problemas de permissão, de Node e de conflito de uma só vez.
Uma correção concreta de PATH (macOS zsh): echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc e depois source ~/.zshrc. No Linux bash, faça o mesmo no ~/.bashrc. Após a mudança, abra um novo terminal.
4. Armadilhas específicas do Windows
No Windows, a falha clássica é executar o comando de instalação no "shell errado." O erro indica qual confusão aconteceu.
Identificando a confusão de shell errado
| Erro | Significado e correção |
|---|---|
'irm' is not recognized ... | Rodou o comando do PowerShell no CMD → use o PowerShell: irm ... | iex |
The token '&&' is not valid | Rodou o comando do CMD no PowerShell → use o comando do CMD |
'bash' is not recognized ... | Rodou o instalador do Linux no Windows → use o instalador do PowerShell |
Outras observações do Windows: (1) Reinicie o terminal após instalar (uma mudança no PATH passa a valer em um novo terminal). (2) Um Claude Desktop antigo que registrou WindowsApps\Claude.exe pode fazer claude abrir o aplicativo de desktop em vez do CLI — atualize o Claude Desktop. (3) Se o Git Bash não for encontrado, aponte CLAUDE_CODE_GIT_BASH_PATH nas configurações para o seu bash.exe. Rodar via WSL também é uma opção.
5. Atualização automática e atualização
Instalações nativas se atualizam automaticamente em segundo plano e passam a valer no próximo início. Para atualizar manualmente, use claude update; para reinstalar/fixar uma versão específica, use claude install <version> (também aceita stable / latest). Verifique o resultado da atualização com claude doctor.
Quando a atualização automática falha na instalação via npm
Se a pasta global do npm não tiver permissão de escrita, a atualização automática falha. claude doctor lista as correções, e a solução de fundo é migrar para uma instalação nativa. Para apenas parar a atualização automática, defina DISABLE_AUTOUPDATER no env das configurações (as atualizações manuais continuam funcionando); para bloquear todas as atualizações, defina DISABLE_UPDATES.
6. O fluxo de diagnóstico
Quando a causa não está clara, vá de cima para baixo. A maioria dos casos se resolve até o passo 3.
Isole de cima para baixo
claude doctor (a partir do shell se ele não iniciar) para verificar a saúde da instalação.which -a claude / where.exe claude para ver onde e quantas estão instaladas (conflitos?).~/.local/bin ao PATH e reinicie o terminal.
A regra: "o binário existe → está no PATH → há conflito?" nessa ordem.
Quando travar, uma reinstalação nativa é o último recurso confiável.
Resumo
O "command not found: claude" do Claude Code é, na maioria dos casos, apenas "o diretório de instalação (~/.local/bin) não está no PATH." O binário existe, então adicione uma linha ao PATH e reinicie o terminal e funciona. Para instalar, o instalador nativo é o recomendado (a versão npm requer Node 18+ e tem mais armadilhas de permissão/PATH). Um EACCES do npm deve ser resolvido mudando para o nativo, não com sudo.
Diagnostique por (1) claude doctor -> (2) which -a claude / where.exe claude para conflitos -> (3) adicionar ~/.local/bin ao PATH -> (4) remover versões extras -> (5) reinstalação nativa. No Windows, fique atento à confusão de shell errado (por exemplo, irm no CMD), à necessidade de reiniciar o terminal e ao antigo conflito do Claude Desktop com Claude.exe. Atualize com claude update / claude install, e pare a atualização automática com DISABLE_AUTOUPDATER. Quando travar, uma reinstalação nativa é a correção confiável. Relacionados: Compilado de erros do Claude Code, erros de autenticação / login.
FAQ
Q. Instalei, mas recebo command not found: claude.
A. Quase com certeza o diretório de instalação não está no seu PATH. Primeiro verifique se o binário existe com ls ~/.local/bin/claude (Windows: %USERPROFILE%\.local\bin); se estiver lá, adicione export PATH="$HOME/.local/bin:$PATH" ao ~/.zshrc/~/.bashrc e abra um novo terminal. A instalação em si geralmente deu certo.
Q. npm install -g falha com um erro de permissão (EACCES).
A. Não use sudo npm (oficialmente desencorajado; convida a problemas de permissão e segurança). O caminho mais rápido e seguro é mudar para o instalador nativo (mac/Linux: curl -fsSL https://claude.ai/install.sh | bash). O build nativo não tem armadilhas de permissão e não precisa de Node. Você também pode mover o prefixo global do npm para um diretório gravável pelo usuário, mas a recomendação oficial é o nativo.
Q. Tenho múltiplas instalações de claude e uma versão antiga é executada.
A. Execute which -a claude (Windows: where.exe claude) para ver todos os claude no PATH. Você pode ter npm-global, Homebrew, WinGet e nativo misturados. Mantenha o nativo (~/.local/bin) e remova os outros (por exemplo, npm uninstall -g @anthropic-ai/claude-code) para ficar com uma única instalação.
Q. No Windows, digitar claude abre o aplicativo de desktop.
A. Um Claude Desktop antigo registrou WindowsApps\Claude.exe, e ele tem prioridade no PATH sobre o CLI. Atualize o Claude Desktop para resolver. Além disso, se não for encontrado ou mostrar uma versão antiga depois de rodar o instalador do PowerShell, reinicie o terminal para que a mudança no PATH passe a valer.
Q. As atualizações não estão funcionando / quero pará-las.
A. Instalações nativas se atualizam automaticamente em segundo plano e passam a valer no próximo início. Manualmente, use claude update; para reinstalar/fixar, claude install <version>. Se a atualização automática falhar numa instalação npm global, é um problema de permissão de escrita — siga o claude doctor e migre para o nativo. Para parar a atualização automática, defina DISABLE_AUTOUPDATER no env das configurações; para bloquear todas as atualizações, defina DISABLE_UPDATES.
