Claude Code: erro command not found e problemas de instalação/PATH

Você instalou o Claude Code, mas digitar claude no terminal devolve isto — soa familiar?

zsh: command not found: claude                                         # macOS
bash: claude: command not found                                        # Linux
'claude' is not recognized as an internal or external command         # Windows CMD
claude : The term 'claude' is not recognized as the name of a cmdlet   # PowerShell

Este 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 — conferido com a documentação oficial em 29 de setembro de 2026.

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.

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 métodos de instalação listados na página oficial de instalação em 29 de setembro de 2026, e onde o binário acaba (o instalador nativo é o recomendado).

O ponto: o instalador nativo é oficialmente recomendado. A versão npm instala o mesmo binário nativo. Desde a v2.1.198 o pacote npm exige Node.js 22 ou mais recente, mas com um Node.js mais antigo o npm só mostra um aviso EBADENGINE e a instalação termina mesmo assim (o binário não usa o Node para rodar). O caminho via npm é mais propenso a problemas de permissão e de PATH, então, 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.

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; com bash no macOS, use o ~/.bash_profile (o Terminal inicia o bash como shell de login, que ignora o ~/.bashrc). No PowerShell do Windows, adicione a pasta ao PATH do usuário com [Environment]::SetEnvironmentVariable('PATH', "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$env:USERPROFILE\.local\bin", 'User'). Após a mudança, abra um novo terminal e confira com claude --version.

"Native installation exists but ~/.local/bin is not in your PATH"

Este aviso aparece na saída do claude doctor (em "Installation warnings") e abaixo do campo de entrada. Como usuários o citaram nas issues oficiais do GitHub, o texto é:

Native installation exists but ~/.local/bin is not in your PATH
Run: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc then open a new terminal or run: source ~/.zshrc

Significa que o binário nativo está em ~/.local/bin, mas essa pasta não está no PATH que o Claude Code enxerga. A correção é a de cima: adicione a linha ao arquivo de configuração do seu shell e abra um novo terminal. Se, num terminal novo, echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin" já mostra a pasta e o aviso continua, você está num caso relatado no GitHub (#63695: PATH definido só no ~/.zshenv e início pelo terminal do VS Code; #75431: claude instalado em outro lugar). Os dois foram fechados sem correção em 29 de setembro de 2026. Se claude --version funciona num terminal novo, a instalação em si está certa.

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.

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) O Git for Windows é opcional: sem ele, o Claude Code roda os comandos pela sua ferramenta de PowerShell. Se o Git está instalado mas o Git Bash não é encontrado, aponte CLAUDE_CODE_GIT_BASH_PATH nas configurações para o seu bash.exe. Rodar via WSL também é uma opção.

VS Code: "Could not locate the Claude CLI on PATH"

A extensão do VS Code mostra este erro no Windows quando você abre o Claude Code no terminal integrado, o shell desse terminal é o PowerShell e a extensão não encontra o claude instalado no PATH. A mensagem começa assim:

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH.

A extensão bloqueia a inicialização porque chamar claude pelo nome no PowerShell poderia rodar um claude da pasta aberta em vez do CLI instalado. (1) Abra uma nova janela do PowerShell fora do VS Code e rode where.exe claude; se nada aparecer, adicione a pasta de instalação ao PATH como na §3. (2) Coloque a entrada do PATH numa variável de ambiente de usuário ou de sistema, não só no seu perfil do PowerShell (a extensão não executa o seu perfil). (3) Reinicie o VS Code, porque ele só lê o PATH ao iniciar.

"'claude' is not recognized" logo após uma atualização

Para se atualizar no Windows, o Claude Code renomeia o claude.exe existente para um backup chamado claude.exe.old. mais um carimbo de data e hora e coloca a nova versão no lugar. Se essa troca falha e a renomeação não pode ser desfeita, o %USERPROFILE%\.local\bin fica com o backup mas sem claude.exe. Restaure o backup mais recente no PowerShell:

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

Depois confira com claude --version. Se não houver nenhum arquivo claude.exe.old.*, reinstale com irm https://claude.ai/install.ps1 | iex. Desde a v2.1.281, uma atualização que falha restaura automaticamente o executável guardado.

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). O resultado da última tentativa de atualização aparece no claude doctor. Instalações por Homebrew, WinGet, apt, dnf e apk não se atualizam sozinhas por padrão; no Homebrew e no WinGet, definir CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 faz o Claude Code rodar a atualização por você.

"Auto-update failed · Run claude doctor"

Quando uma atualização em segundo plano falha, a sessão aberta mostra isso na área de status. As issues do GitHub citam duas formas: Auto-update failed · Run claude doctor (da v2.1.220 à v2.1.278) e, em instalações npm de versões anteriores, Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code. Resolva nesta ordem:

1. Rode claude doctor num terminal — ele mostra o resultado da última tentativa de atualização e eventuais avisos de instalação.
2. Rode claude update para aplicar a atualização agora. Ele responde Successfully updated from <old version> to version <new version>, ou Claude Code is up to date (<version>) se não houver nada pendente.
3. Se você já está atualizado, a falha foi passageira (por exemplo, uma queda de rede). Segundo issues do GitHub (#89286, #96038), o aviso pode continuar visível até reiniciar a sessão.
4. Numa instalação npm global cuja pasta não aceita escrita, a atualização automática não funciona — passe para o instalador nativo (veja o quadro acima).
5. Se continuar falhando numa rede corporativa, verifique se downloads.claude.ai está acessível.

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.

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 pede Node.js 22+ 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 aparecer Auto-update failed · Run claude doctor, rode claude doctor e depois claude update; se ele disser que você já está atualizado, reiniciar a sessão faz o aviso sumir. 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.