Como instalar o Claude Code pelo npm sem quebrar seu ambiente?

Fala aí, beleza? Instalar o Claude Code pelo npm é uma linha só de comando, e mesmo assim é exatamente aí que muita gente empaca

Você roda o install global, o npm diz que deu tudo certo, você digita claude e o terminal responde command not found 😅

A instalação em si é rápida, mas ela tem três pontos que costumam travar quem nunca mexeu com pacote global: a versão do Node, o sudo e o PATH

E tem um detalhe de contexto que quase ninguém conta: na documentação oficial de instalação o método npm está DEPRECIADO, a instalação nativa é a recomendada

Isso não significa que o npm parou de funcionar, se liga: ele funciona e instala exatamente o mesmo binário nativo, só que existe um caminho oficial preferido hoje

Bora ver os dois na prática?

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Pré-requisitos antes de rodar o npm install

Antes de sair colando comando no terminal, confere esse checklist…

Conta com acesso ao Claude Code:

O Claude Code exige conta Pro, Max, Team, Enterprise ou Console

O plano gratuito do Claude.ai NÃO dá acesso, então se é esse o seu caso, instalar não vai te levar muito longe

Se você ainda tá decidindo qual plano do Claude Code assinar, resolve isso antes de instalar, é mais fácil

Também dá pra ir pelo caminho da API: a variável de ambiente ANTHROPIC_API_KEY com uma chave do Claude Console habilita o acesso direto à API

Requisitos de sistema:

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

Nada de PC da Nasa aqui, beleza? é um requisito bem camarada

Node.js 22 ou superior:

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

Se você tá numa versão mais antiga, calma: o npm mostra o aviso EBADENGINE durante a instalação em vez de falhar

A instalação conclui e o claude roda mesmo assim, porque o pacote baixa um binário nativo que não usa o Node.js em tempo de execução

Plataformas suportadas na instalação via npm:

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

Permissão de escrita nas pastas certas:

No macOS e no Linux o instalador precisa de acesso de escrita a ~/.local/bin/ e ~/.claude/

Guarda esse primeiro caminho na cabeça, ele volta lá na parte do command not found 😀

Git for Windows (opcional, mas recomendado):

No Windows nativo, o Git for Windows é recomendado (e opcional) pra que o Claude Code use a ferramenta Bash via Git Bash

Sem ele, o Claude Code usa o PowerShell como shell

Já quem roda em WSL não precisa do Git for Windows

Passo a passo: instalando o Claude Code pelo npm

Agora sim, mão na massa

1. Confira a versão do Node

node --version

O erro comum deste passo é ignorar a versão e depois se assustar com o aviso na tela

Se o número for menor que 22, o npm vai cuspir um EBADENGINE na instalação: é aviso, não é falha fatal, a instalação conclui e o claude roda

2. Rode a instalação global

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

O erro comum deste passo é o clássico: dar sudo npm install -g quando aparece qualquer coisa parecida com permissão

A doc oficial pede pra NÃO usar sudo aqui, porque isso leva a problemas de permissão e a riscos de segurança

Tome cuidado! esse é o tipo de atalho que resolve hoje e te dá dor de cabeça em toda atualização futura

3. Entenda o que o npm acabou de baixar

Esse passo não tem comando, mas evita confusão depois

O pacote npm puxa o binário por uma dependência opcional específica da sua plataforma (tipo @anthropic-ai/claude-code-darwin-arm64) e um passo de postinstall faz o link

Ou seja: o binário claude que ficou na sua máquina é o mesmo do instalador standalone, e ele não invoca o Node

4. Valide se a instalação funcionou

claude --version

A saída é o número da versão, no formato que a doc usa de exemplo: 2.1.211 (Claude Code)

Esse número do exemplo é só ilustração do formato, beleza? o que vai aparecer no teu terminal é a versão que você acabou de instalar, e ela muda o tempo todo

O erro comum deste passo é interpretar um command not found aqui como "a instalação falhou", quando na maioria das vezes é só PATH (a próxima seção é inteirinha sobre isso)

5. Rode o diagnóstico

claude doctor

Ele imprime diagnósticos somente leitura da instalação e das configurações, sem iniciar sessão: saúde da instalação, erros de validação dos arquivos de settings e avisos com sugestões de correção

É o comando que eu rodaria ANTES de sair caçando problema no escuro

O comando claude não aparece no terminal: o que checar

Aqui mora a maior parte do sofrimento de quem instala pacote global pela primeira vez

Vamos por sintoma…

Sintoma: o terminal responde "command not found"

Causa: o instalador coloca o claude em ~/.local/bin/claude no macOS e no Linux, e em %USERPROFILE%\.local\bin\claude.exe no Windows

Se o comando não é reconhecido, esse diretório não está no seu PATH

Solução: garantir que esse diretório esteja no PATH do seu shell

Como prevenir: depois de qualquer instalação global, confere com claude --version na hora, e não duas semanas depois quando você já esqueceu o que fez

Sintoma: instalei, mas o terminal continua não achando

Causa: a sessão em que você instalou mantém o PATH antigo

Solução: abre uma janela NOVA de terminal e tenta de novo, esse é o teste mais barato que existe

Como prevenir: já pega o hábito de fechar e reabrir o terminal depois de instalar qualquer coisa global

Sintoma: aviso na inicialização dizendo que ele não consegue se auto-atualizar

Causa: o diretório global do npm não está gravável, e nesse caso o Claude Code exibe um aviso único na inicialização informando que não consegue se auto-atualizar

Solução: ou você resolve a permissão do diretório global, ou passa a atualizar na mão (o comando tá na próxima seção)

Como prevenir: aquele sudo que a gente evitou no passo 2 é justamente pra não cair nesse tipo de nó de permissão

Sintoma: apareceu EBADENGINE no meio da instalação

Causa: seu Node.js é mais antigo que o exigido pelo pacote (Node.js 22+ a partir da v2.1.198)

Solução: nenhuma urgente, o npm só avisa: a instalação conclui e o claude roda, porque o binário nativo não depende do Node em runtime

Como prevenir: subir o Node pra 22+ se você quer o terminal limpo, sem aviso amarelo toda vez

E em qualquer um desses casos, claude doctor é o teu melhor amigo: ele te diz o estado da instalação e dos settings sem você precisar adivinhar nada

Como atualizar ou migrar a instalação feita pelo npm

Depois que tá tudo de pé, existem dois caminhos e os dois são válidos

1. Continuar no npm e só atualizar

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

2. Migrar pra instalação nativa, que é o método recomendado pela doc

claude install

Esse é o comando oficial pra migrar uma instalação existente feita por npm pra instalação nativa

E se você tá começando do zero numa máquina nova, dá pra ir direto pelo instalador nativo, que muda conforme o sistema:

• macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash
• Homebrew: brew install --cask claude-code
• Windows (PowerShell): irm https://claude.ai/install.ps1 | iex
• WinGet: winget install Anthropic.ClaudeCode

Se a ideia é justamente baixar e instalar no computador do zero, esse é o caminho mais curto

E por que isso importa? porque os dois caminhos convergem no mesmo lugar

Antes da v2.1.113, o pacote npm entregava o Claude Code como JavaScript rodando direto no Node

Da v2.1.113 em diante ele passou a entregar o binário nativo, o mesmo do instalador standalone

Ou seja: migrar não é trocar de ferramenta, é trocar a porta de entrada do MESMO binário

Na hora da consulta pra este post, a última versão publicada do pacote no npm era a 2.1.222

Na prática: o PATH que me pegou numa VPS Ubuntu

Agora sim a parte que eu vivi na pele

No vídeo abaixo eu monto uma operação inteira de agentes com Claude Code, e o Claude Code é pré-requisito da coisa toda funcionar

Eu fiz o passo a passo do zero numa VPS Ubuntu, não no PC local, justamente porque eu recomendo rodar esse tipo de processo em VPS dedicada: aí a operação fica de pé sem depender do teu computador ligado

O pré-requisito ali era ter o Node na máquina, então instalei o Node pelo gerenciador de pacotes do sistema e, na sequência, instalei o pnpm globalmente com npm install -g pnpm

E olha a ironia: quando fui conferir a instalação pelo comando de versão, o pnpm simplesmente não respondeu

O pacote tinha sido instalado num diretório que não estava no PATH do meu usuário

Tentei primeiro recarregar o shell com source no arquivo de configuração do bash, e NÃO resolveu no meu caso

O que funcionou foi descobrir onde o npm instala os pacotes globais:

npm config get prefix

Com o caminho em mãos, eu exportei ele pro PATH e adicionei a linha no arquivo de configuração do shell

E olha, esse erro pode simplesmente não acontecer na tua máquina, beleza? é uma coisa de ambiente, não uma etapa obrigatória do tutorial

Aí aconteceu uma coisa que me pegou de novo: eu criei um usuário não root pra rodar a aplicação (o banco de dados usado pela ferramenta bloqueia acesso pelo root, e isso é proteção padrão de VPS)

E o problema de PATH VOLTOU no usuário novo

Pacote global instalado por um usuário não valeu pro outro, então tive que refazer a instalação e a exportação do caminho lá também

Já me ferrei uma vez por causa disso, agora eu já vou direto conferir o prefixo

Na VPS eu instalei o Claude Code usando o pnpm (não o npm) e conferi rodando o comando de versão do claude

Depois fiz o login na conta pelo próprio terminal, e comentei no vídeo que também daria pra autenticar por chave de API

O detalhe mais gostoso de ver: o teste de ambiente da ferramenta FALHAVA enquanto o Claude Code não estava instalado e autenticado no servidor, e só passou depois da instalação e do login

É a prova viva de que ajustar o ambiente direito antes de começar não é frescura, é o que destrava tudo que vem depois

Ah, e o painel eu acessei por túnel SSH em vez de abrir porta no servidor, porque a aplicação não tem autenticação própria e ficaria exposta

Conclusão

Recapitulando o caminho seguro pra instalar o Claude Code pelo npm:

• Node.js 22 ou superior (abaixo disso é só o aviso EBADENGINE, não é o fim do mundo)
• conta Pro, Max, Team, Enterprise ou Console, ou ANTHROPIC_API_KEY do Console
• npm install -g @anthropic-ai/claude-code, sem sudo
• PATH conferido, lembrando que o binário vive em ~/.local/bin/claude (ou %USERPROFILE%\.local\bin\claude.exe no Windows)
• terminal NOVO antes de dizer que não funcionou
• claude --version pra validar e claude doctor pra diagnosticar

O próximo passo é bem concreto: abre a pasta do teu projeto, roda claude e começa a trabalhar

E se você quiser já entrar no método recomendado pela doc, roda claude install e migra pra instalação nativa, o binário é o mesmo

até o próximo post! 😀