npm install anthropic-ai/claude code deu erro? Como ler a mensagem e descobrir o que faltou

Fala aí, beleza? Aquele erro que aparece na hora de instalar o Claude Code quase nunca é a sua máquina pegando fogo: na maioria das vezes é o nome do pacote escrito errado

Se você digitou npm install anthropic-ai/claude code, já tem dois problemas antes mesmo do npm sair do lugar: sumiu o @ do escopo e entrou um espaço onde deveria ter hífen

O nome oficial do pacote é @anthropic-ai/claude-code

E olha que legal: a mensagem que o npm cospe no terminal já te conta qual dos dois mundos quebrou, o que você digitou ou o ambiente onde você digitou

Então bora fazer o contrário do que todo mundo faz? Em vez de sair colando comando aleatório até um funcionar, vamos LER o erro primeiro

Como ler a mensagem de erro do npm em 3 partes:

A mensagem parece um muro de texto, mas ela tem estrutura

A triagem é essa:

1. Procure o código em maiúsculas: E404, EACCES, EBADENGINE. É ele que classifica o problema, não o parágrafo bonito embaixo
2. Veja qual nome de pacote o npm repetiu de volta pra você. Se voltou um nome estranho, sem @, com espaço, ou um endereço de GitHub, o culpado é o que você digitou
3. Confira do que a linha está falando: registro, permissão do sistema ou versão de ambiente

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

A regra prática que resolve a maior parte da confusão:

Código que fala de pacote ou versão aponta pro teclado

Código que fala de permissão ou de engine aponta pra máquina

Só de ler a primeira linha antes de copiar o próximo comando, você já economiza meia hora de reinstalação às cegas =)

npm ERR! code E404: o pacote que você pediu não existe no registro

O E404 significa Not Found: o pacote (ou a versão pedida) não foi encontrado no registro

E a causa mais comum aqui é justamente a busca que te trouxe até este post

Que causa? Escrever o nome no formato nome/nome, sem o @

No npm, escopo é SEMPRE precedido de arroba e seguido de barra, no formato @escopo/nome-do-pacote

Quando você tira o @, o npm nem procura no registro: ele interpreta npm install <githubname>/<githubrepo> como atalho de repositório do GitHub e tenta clonar https://github.com/githubname/githubrepo com git

Ou seja, tu pediu uma coisa e ele foi buscar em outro lugar, e por isso a mensagem parece não fazer sentido nenhum

O comando certo é esse:

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

Detalhe divertido: existe um pacote não escopado chamado claude-code no npm, e ele é só um marcador com o aviso "This is not the package you’re looking for!", direcionando pro @anthropic-ai/claude-code haha

Se você quiser entender melhor o que vem dentro do pacote oficial, dá uma olhada depois, ajuda a reconhecer quando o nome está certo

Tome cuidado! Existe um segundo motivo de E404 que não é digitação: espelho ou registro corporativo

O registro precisa espelhar os oito pacotes de plataforma @anthropic-ai/claude-code-* além do pacote principal. Se o espelho da empresa só replicou o principal, o E404 vem na instalação mesmo com o nome perfeito

Como prevenir? Copie o nome do pacote em vez de digitar, sério

npm ERR! code EACCES: é permissão do sistema, não do pacote

Esse aqui aparece muito com -g

O EACCES quer dizer que a operação foi rejeitada pelo sistema operacional: provavelmente o usuário atual não tem permissão de acesso àquele arquivo ou diretório

Repare que isso não tem NADA a ver com o pacote existir ou não

A solução documentada pelo próprio npm é mudar o diretório global do npm para um diretório do seu usuário. Tem página oficial só pra isso, a "Resolving EACCES permissions errors when installing packages globally"

E agora o aviso duro, porque esse é o reflexo de todo mundo:

não sai jogando sudo npm install -g

A documentação oficial desaconselha explicitamente, porque o sudo cria arquivos com dono root que quebram as atualizações futuras. A orientação é trocar pelo instalador nativo ou corrigir o diretório global do npm

É aquele clássico: resolve hoje, te ferra daqui a duas semanas quando você for atualizar

Se o seu caso for esse combo de permissão com outras dores de ambiente, tem um post daqui sobre erros comuns ao instalar o Claude Code que cobre esse terreno com mais calma

npm WARN EBADENGINE: sua versão de Node não bate com a exigida

O EBADENGINE compara duas coisas na tela: required (o campo engines do package.json do pacote) e current (o Node e o npm que você tem instalado)

A partir da v2.1.198, o pacote npm do Claude Code exige Node.js 22 ou superior

Agora o detalhe que evita pânico, e é MUITO importante:

em Node mais antigo o npm imprime o aviso em vez de falhar

A instalação conclui, e o claude roda

Como assim? Porque o pacote baixa um binário nativo que não usa o Node em tempo de execução

Ou seja: viu WARN e não ERR!? Respira, testa o comando antes de sair reinstalando o mundo

Pra prevenir de vez, atualize o Node ou use o instalador nativo, que não depende de Node nem de npm

Erro de plataforma: quando o problema é o sistema, não o comando

Sintoma chato: o nome está certo, mas a instalação falha ou o binário não roda

Aqui vale entender COMO o pacote npm funciona por baixo: ele instala o mesmo binário nativo do instalador padrão, puxando esse binário por dependência opcional por plataforma e ligando tudo num passo de postinstall

E a lista de plataformas suportadas é fixa:

• darwin-arm64
• darwin-x64
• linux-x64
• linux-arm64
• linux-x64-musl
• linux-arm64-musl
• win32-x64
• win32-arm64

Tem um caso relatado que pega gente de Mac Apple Silicon desprevenida: rodando Node x64 sob Rosetta 2, o npm instala só o binário darwin-x64, que exige AVX, e o Rosetta não emula isso

A solução relatada nesse caso é instalar o Node arm64 e reinstalar

E antes de culpar o npm, confere os requisitos oficiais de sistema:

• macOS 13.0+, Windows 10 1809+ ou Windows Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
• 4 GB+ de RAM
• processador x64 ou ARM64
• conexão com internet

Não precisa do PC da Nasa, mas precisa estar dentro da lista 🙂

Instalou sem erro mas o comando claude não é encontrado?

Esse é o erro que mais confunde, porque o npm terminou feliz e o terminal responde que o comando não existe

O primeiro suspeito é o PATH

Com o instalador nativo, o binário fica em caminho conhecido: ~/.local/bin/claude no macOS, Linux e WSL, e %USERPROFILE%\.local\bin\claude.exe no Windows

E existe um diagnóstico oficial pra não ficar chutando:

claude doctor

Ele é um relatório somente leitura, não abre sessão

Dentro de uma sessão do Claude Code, o equivalente é /doctor

Rodar o diagnóstico antes de reinstalar às cegas é o passo que quase ninguém faz e que economiza mais tempo

Erro que não é do npm: você está no shell errado no Windows

Esse aqui é ouro puro pra quem copia comando de tutorial

Duas mensagens denunciam o shell trocado:

• The token '&&' is not a valid statement separator significa que você está no PowerShell, e não no CMD
• 'irm' is not recognized as an internal or external command significa o contrário: você está no CMD, e não no PowerShell

Percebeu? O pacote está ok, o comando é que foi colado no lugar errado

Solução: identifique o shell ANTES de colar

Os shells suportados são Bash, Zsh, PowerShell ou CMD

E no Windows nativo o Git for Windows é recomendado, pra que o Claude Code consiga usar a ferramenta Bash. Sem ele, o Claude Code usa PowerShell como shell

Você queria o CLI ou o SDK? Dois pacotes parecidos

Outro sintoma clássico: instalou, não deu erro nenhum, e o comando de terminal esperado simplesmente não aparece

A diferença mora em poucas letras no nome do pacote, e ela muda TUDO

Dá uma olhada no nome que você instalou

@anthropic-ai/claude-agent-sdk é OUTRO pacote: é o SDK para construir agentes com as capacidades do Claude Code, em TypeScript ou Python, feito pra embutir em scripts, servidores e pipelines

@anthropic-ai/claude-code é o CLI, aquele que você chama no terminal

São coisas diferentes pra objetivos diferentes, e nenhum dos dois está quebrado quando você pega o errado

Se o seu objetivo é rodar o claude no terminal, o nome é o do CLI. Se é embutir a capacidade dentro do seu código, é o do SDK

Decide o objetivo antes de escolher o nome e você pula esse erro inteiro

Como evitar tudo isso: o instalador nativo

O método recomendado hoje não depende de Node nem de npm, o que mata de uma vez os erros de engine, de permissão global e de espelho corporativo

macOS e Linux:

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

Windows PowerShell:

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

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

E se eu JÁ instalei pelo npm? Dá pra migrar:

Dá, e não precisa sair desinstalando na mão: existe um caminho oficial de migração de quem instalou por npm pro instalador nativo

São duas portas pra mesma coisa:

• /migrate-installer dentro de uma sessão do Claude Code
• claude install direto no shell

É o movimento natural pra quem começou pelo npm e apanhou de EACCES, de EBADENGINE ou de espelho corporativo no meio do caminho: sai da dependência de Node e npm e fica só com o binário nativo daqui pra frente

O que vem depois da instalação funcionar:

Instalar é o começo, o barulho de verdade começa quando você põe a ferramenta pra trabalhar

No vídeo abaixo eu mostro o Printing Press rodando, e no meio da gravação aconteceu exatamente o tipo de erro que este post está discutindo

Rodei o comando logo depois de instalar e o terminal respondeu que não reconhecia o comando

Aí eu parei pra separar duas hipóteses: cache do terminal ou falha na instalação?

Não era nenhuma das duas

Eu tinha digitado o nome do comando errado, simples assim. Escrevi certo e ele respondeu normalmente haha

Moral: o primeiro suspeito de "comando não reconhecido" é erro humano no comando digitado, não a ferramenta

Outra coisa que eu mostro por lá: depois de instalar um pré-requisito, a checagem mais simples do mundo é abrir o terminal e pedir a versão da ferramenta, só pra confirmar que ela está mesmo instalada antes de seguir

E teve o caso mais interessante: ao instalar um pacote pronto, o CLI foi instalado com sucesso, mas a etapa da skill falhou

Li a mensagem e tratei como DUAS coisas separadas, não como instalação totalmente quebrada

Tanto que confirmei a parte que funcionou rodando o comando de versão do CLI, mesmo com a skill tendo falhado

Depois tentei um segundo comando só pra instalar a skill, a falha se repetiu, e só na terceira variação do comando concluiu

E não foi azar da gravação: eu já tinha esbarrado nesse mesmo erro antes seguindo a documentação

A dica que ficou: em vez de adivinhar a sintaxe, usa a flag de ajuda do comando pra descobrir a estrutura de comandos e flags disponíveis

Nem toda mensagem de erro na instalação significa instalação quebrada: uma parte pode ter subido e outra não

Conclusão: leia o código do erro antes de reinstalar

A triagem inteira cabe numa frase: o código em maiúsculas te diz se o problema é digitação, permissão, versão ou plataforma

E404 olha pro que você digitou (ou pro espelho do registro)

EACCES e EBADENGINE olham pra sua máquina

Erro de separador && ou de irm nem é do npm, é shell trocado no Windows

O próximo passo concreto é curtinho: usa o nome escopado completo, npm install -g @anthropic-ai/claude-code, roda claude doctor se alguma coisa ficar estranha depois, e considera o instalador nativo pra não depender do npm nunca mais

assim tu para de reinstalar às cegas e passa a resolver na primeira linha da mensagem 😀

até o próximo post!