Como instalar o Claude Code via npm no terminal (passo a passo e o que mudou)

Fala aí, beleza? O comando que todo mundo digita no Google é npm install -g @anthropic-ai/claude-code, ele ainda funciona, mas hoje ele não é mais o caminho oficial

E isso confunde MUITA gente, porque as duas coisas são verdade ao mesmo tempo: o pacote npm existe, continua publicado e recebendo versões novas, e ao mesmo tempo a documentação oficial marcou a instalação via npm como descontinuada (deprecated)

Então a ideia aqui é te entregar os dois lados: o passo a passo completo pra instalar Claude Code via npm, e também o método recomendado pela Anthropic, pra você escolher sabendo exatamente o que está escolhendo

Bora?

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

O que mudou: npm virou deprecated na documentação oficial

Antes de sair rodando comando, entende o estado atual pra não se frustrar depois

A documentação oficial de setup marca a instalação via npm como deprecated e orienta usar um dos métodos recomendados

O instalador nativo é o caminho principal testado e suportado pela Anthropic

O que isso NÃO significa:

Não significa que o pacote sumiu, beleza?

O pacote @anthropic-ai/claude-code no npm segue publicado e recebendo versões novas: a versão 2.1.221 foi publicada cerca de 18 horas antes da consulta feita em 04/08/2026

Ou seja: deprecated na doc, vivo no registro

A diferença prática entre os dois:

A distinção que realmente muda a sua vida é essa: o instalador nativo não depende de Node.js nem de npm, e se atualiza sozinho em segundo plano

A via npm te deixa amarrado no ecossistema Node pra instalar e pra atualizar

Se você quer um panorama de todas as formas de colocar a ferramenta na máquina, tem um passo a passo dedicado ao download do Claude Code aqui no blog também

Pré-requisitos antes de instalar o Claude Code

Checklist rápido do que precisa estar de pé antes do primeiro comando:

• Node.js 22 ou superior (o pacote pede, mas não bloqueia): a partir da v2.1.198 o pacote npm pede Node.js 22+, só que em versão mais antiga o npm apenas mostra um aviso EBADENGINE e a instalação conclui do mesmo jeito (explico direitinho no passo 2)
• npm com dependências opcionais permitidas: o binário chega por uma dependência opcional por plataforma (ex.: @anthropic-ai/claude-code-darwin-arm64) e um passo de postinstall faz o link
• No Windows: Windows 10 versão 1809 ou posterior
• Uma conta pro login: assinatura Claude.ai (Pro, Max, Team ou Enterprise) ou conta do Anthropic Console com cobrança por uso via API

Por que as dependências opcionais importam tanto?

Aqui é o ponto que pega quem roda instalação com flag pra ignorar optional deps (comum em pipeline enxuto)

O npm não baixa "o Claude Code" em um pacote só: ele puxa o binário certo da sua plataforma por uma dependência opcional, e o postinstall faz o link

Bloqueou dependência opcional, quebrou a instalação

Sacou a diferença? Essa aqui é a trava de verdade, a do Node.js não é

Windows nativo ou WSL?

Os dois rolam

O Claude Code roda nativamente no Windows ou dentro do WSL, com WSL 1 e WSL 2 suportados, sendo que o WSL 1 tem suporte limitado (sem sandboxing da ferramenta Bash)

No Windows nativo, o Git for Windows é recomendado pra habilitar a ferramenta Bash

Sem ele, o Claude Code usa o PowerShell como shell

Em WSL isso não é necessário

Passo a passo: instalar o Claude Code via npm

Agora sim, do zero até o terminal respondendo

1. Rode a instalação global

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

O erro comum deste passo: colocar sudo na frente

A doc oficial orienta a NÃO usar sudo npm install -g, por risco de problemas de permissão e de segurança

Se deu erro de permissão, resolve a permissão do npm global, não empurra com sudo

2. Entenda o aviso EBADENGINE se ele aparecer

Em versão de Node.js mais antiga, o npm mostra um aviso EBADENGINE em vez de falhar, e a instalação conclui do mesmo jeito

Por quê? Porque o pacote baixa um binário nativo que não usa o Node.js em tempo de execução

É por isso que o Node.js 22+ aparece como pedido do pacote e não como trava: o aviso avisa, mas não impede nada

O erro comum aqui é achar que quebrou tudo e entrar naquele loop de desinstalar, limpar cache e reinstalar cinco vezes

Aviso não é falha, se liga nisso

3. Confirme que a instalação pegou

claude --version

Também funciona na forma curta:

claude -v

O erro comum deste passo: rodar o comando na mesma aba de terminal que já estava aberta antes da instalação

Abre um terminal novo e testa de novo antes de achar que não instalou

4. Rode o diagnóstico

claude doctor

Esse aqui é subestimado

Ele imprime um diagnóstico somente leitura da instalação e das configurações, sem abrir sessão: saúde da instalação, erros de validação do arquivo de settings e avisos com sugestões de correção

E ainda mostra o resultado da última tentativa de atualização

5. Abra a primeira sessão

Abra o terminal na pasta do projeto e rode:

claude

A interface mostra a versão, o modelo atual e o diretório de trabalho logo acima do prompt

No primeiro uso o login é solicitado: para conta de assinatura Claude ou do Console, a autenticação é concluída no navegador e as credenciais ficam salvas depois disso

Se travou em algum ponto da instalação ou do login, o destino certo é a página oficial de solução de problemas de instalação

Alternativa recomendada: instalar pelo instalador nativo

Se você prefere seguir a recomendação da doc, é ainda mais curto

1. macOS e Linux

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

2. Windows (PowerShell)

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

3. Homebrew

brew install --cask claude-code

4. WinGet

winget install Anthropic.ClaudeCode

Onde o lançador fica depois disso?

No macOS e no Linux, o instalador nativo mantém o lançador em ~/.local/bin/claude, como symlink para ~/.local/share/claude/versions/

Saber isso ajuda quando o terminal diz que o comando não existe: quase sempre é ~/.local/bin fora do PATH, não instalação corrompida

A validação é a mesma de sempre: claude --version e depois claude doctor

Como atualizar ou migrar da instalação via npm

São dois caminhos, e eles resolvem coisas diferentes

1. Continuar no npm e só atualizar

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

Faz sentido se o seu ambiente já é todo apoiado em npm e você quer o mínimo de mudança agora

2. Sair da instalação global via npm e migrar pra local

claude migrate-installer

Esse é o comando oficial pra deixar o global do npm pra trás e passar pra instalação local

Faz sentido se você já decidiu seguir a recomendação da doc e não quer manter a ferramenta dependendo do Node.js pra atualizar

npm ou instalador nativo: qual escolher no seu caso

Se o seu uso passa por automação de repositório, vale olhar depois como rodar a ferramenta em automação de CI/CD com IA, que é outro papo de ambiente

Conclusão

Veredito honesto: instalar Claude Code via npm funciona, o pacote está lá e continua ganhando versões novas, mas a documentação oficial já aponta pra outro caminho

Se você só quer resolver hoje, roda o npm install -g @anthropic-ai/claude-code e segue

Se você quer o caminho testado e suportado, vai de instalador nativo, ou usa o claude migrate-installer pra sair do global do npm

E o próximo passo prático é sempre o mesmo, independente da via escolhida: roda claude --version, depois claude doctor, e aí abre a pasta do projeto no terminal e roda claude pra fazer o login pelo navegador

Deu problema no meio? A página oficial de solução de problemas de instalação e login é o destino, não o fórum aleatório do Google 😀

até o próximo post!