Erro ao instalar o Claude Code no Windows e no Mac: como resolver os problemas mais comuns

Instalar o Claude Code parece que vai dar trabalho, mas na prática ele trava quase sempre nos MESMOS poucos erros

PATH que não reconhece o comando, permissão negada no npm, Node antigo, permissão estranha no WSL e login que não passa

Se liga: a maioria desses casos tem conserto rápido, e o mesmo comando de diagnóstico resolve boa parte do mistério

Aqui a gente vai direto por sintoma, causa e solução, cobrindo Windows, Mac, Linux e WSL. Bora?

‘command not found: claude’ depois de instalar

Esse é o campeão de audiência

Você instala, o instalador diz que deu certo, você digita claude e o terminal responde command not found: claude (ou ‘não é reconhecido como comando’, no Windows)

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Causa: a pasta onde o binário foi instalado não está no seu PATH. O sistema simplesmente não sabe onde procurar o executável

No Mac e no Linux o binário fica em ~/.local/bin/claude

No Windows, em %USERPROFILE%\.local\bin\claude.exe

Solução: adicionar essa pasta ao PATH e, MUITO importante, abrir um novo terminal depois

1. Confirme onde o binário está: ~/.local/bin no Mac/Linux ou %USERPROFILE%\.local\bin no Windows
2. Adicione essa pasta ao seu PATH. O erro comum aqui é editar o PATH e continuar testando na MESMA janela do terminal: a alteração só vale em um terminal novo
3. Feche e reabra o terminal, aí rode de novo:

claude doctor

O claude doctor verifica tipo de instalação, PATH, autenticação e configuração de uma vez, então ele te diz na lata se a pasta entrou no PATH ou não

Prevenir é fácil: sempre reabra o terminal depois de instalar e passe o claude doctor antes de sair caçando problema que não existe

Erro EACCES no npm (e por que não usar sudo)

Esse aparece quando você instala pelo método via npm e leva um EACCES ou ‘permission denied’ na cara

Causa: o prefixo global do npm pertence ao root. Aí o npm tenta escrever numa pasta que o seu usuário não tem permissão de mexer, e trava

A tentação natural é resolver na marra com sudo. NÃO faça isso

sudo npm install -g @anthropic-ai/claude-code

O problema desse comando é traiçoeiro: ele cria arquivos com dono root, e esses arquivos quebram as ATUALIZAÇÕES futuras do Claude Code. Você resolve hoje e se ferra semana que vem

Solução: usar o instalador nativo, que é o método recomendado pela Anthropic e não exige root

No Mac, Linux e WSL:

curl -fsSL https://claude.ai/install.sh | bash

No Windows, pelo PowerShell:

irm https://claude.ai/install.ps1 | iex

Prevenir aqui é escolher certo desde o começo: se você ainda não instalou, vai pelo instalador nativo e nem chega a esbarrar no EACCES

Erro de permissão (EPERM) no WSL

Se você usa WSL e toma um EPERM ou falhas de permissão do nada, presta atenção em ONDE está o seu projeto

Causa: projetos em /mnt/c/ rodam sobre o driver NTFS do Windows. E o NTFS não suporta todas as operações de permissão do Linux que o Claude Code espera fazer. Aí dá ruído

Solução: mover o projeto pra fora de /mnt/c/, pro sistema de arquivos Linux do próprio WSL (tipo dentro do seu ~)

É meio contraintuitivo pra quem tá acostumado a abrir a pasta do Windows de dentro do WSL, mas é o que evita o problema

Prevenir: mantenha seus projetos no sistema de arquivos Linux do WSL desde o início, não em /mnt/c/

Node.js antigo derruba a instalação via npm

Mais um clássico do caminho via npm

Você tenta instalar e a coisa falha com erro de versão, ou o pacote simplesmente não sobe

Causa: sua versão do Node está abaixo do mínimo. O método npm exige Node.js 18 ou superior

Solução: checar a versão antes de brigar com o instalador

node -v

Se voltar algo abaixo de 18, atualize o Node. Se não quiser depender disso, a saída mais limpa é usar o instalador nativo, que dispensa Node e npm por completo

Prevenir: valide o node -v ANTES de tentar instalar por npm. Dois segundos que economizam meia hora

Não consigo autenticar ou fazer login

Às vezes a instalação foi de boa, mas o login trava depois

Solução: comece pelo diagnóstico

claude doctor

Ele checa o estado da autenticação junto com PATH e configuração, então te dá uma pista de onde está o nó

Se o problema persistir, a Anthropic mantém uma página oficial de troubleshooting de instalação e login. Vale consultar direto na fonte em code.claude.com/docs/en/troubleshoot-install e no support.claude.com, em vez de sair seguindo passo de menu que alguém inventou num fórum

Conclusão

No fim, quase todo erro ao instalar Claude Code cai nesses poucos suspeitos: PATH, permissão de root, Node velho, pasta errada no WSL ou login que não passa

O reflexo que resolve a maioria é sempre o mesmo:

• Rode claude doctor primeiro, pra diagnosticar em vez de chutar
• Prefira o instalador nativo, que não exige root e te livra dos erros de permissão
• Quando o erro insistir, vá na página oficial de troubleshooting, não em achismo de terceiro

E se você ainda nem chegou nessa parte, o certo é começar do começo: dá uma olhada no guia completo de instalação do Claude Code e volta aqui se algum desses erros aparecer 😉