Como atualizar o Claude Code e resolver erros de versão no CLI (Windows e Mac)

Você roda o comando de atualização, ele diz que terminou, mas a versão continua a mesma

Se liga: atualizar o Claude Code é rápido, quase sempre é um comando só

O que trava não é o update em si, é o conflito entre os jeitos que você instalou a ferramenta

Bora destravar a versão do CLI e fazer o número mudar de verdade?

Antes de atualizar: descubra como você instalou

Existe mais de um jeito de ter o Claude Code na máquina, e o comando de update certo MUDA conforme o método

Instalação nativa, npm, Homebrew no Mac, WinGet no Windows: cada uma se atualiza de um jeito

Então o primeiro passo não é atualizar, é descobrir o que você tem instalado

Pra isso tem um comando de diagnóstico que só lê, não mexe em nada:

claude doctor

Ele mostra a saúde da instalação, o TIPO de instalação, a versão, o PATH, o ripgrep e o status do auto-update, tudo sem abrir uma sessão do Claude Code

É o raio-x antes de sair rodando comando

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

E no Windows?

No Windows você roda isso do PowerShell ou do CMD, tanto faz

E não precisa ser Administrador pro install nativo

O Git for Windows é opcional: ele habilita a ferramenta Bash via Git Bash, mas não é obrigatório pro Claude Code rodar

Se você já teve que atualizar o git no Windows alguma vez, a lógica de manter a ferramenta em dia é bem parecida

Passo a passo para atualizar o Claude Code

Agora que você sabe como instalou, é escolher o caminho

O passo 1 é o coringa pra forçar a versão na hora

Mas se você instalou por um gerenciador de pacote (npm, Homebrew, WinGet), os passos 2 a 4 são o caminho mais limpo, porque é o gerenciador que controla aquele binário e é ele que mantém tudo em sincronia

1. Force a versão mais recente com claude update

Esse é o coringa

claude update

Ele atualiza o Claude Code pra versão mais recente na hora, sem esperar a verificação automática que roda de vez em quando

O erro comum deste passo: achar que precisa reinstalar tudo

Não precisa

As instalações nativas até se atualizam sozinhas em segundo plano, e o claude update serve pra forçar quando você não quer esperar

Agora, se você instalou via npm, Homebrew ou WinGet, o update que mantém aquele binário em sincronia é o do próprio gerenciador, ali nos passos seguintes

2. Instalou via npm? Use o update do npm

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

O erro comum deste passo: rodar sem o -g

O Claude Code é global, então o -g tem que estar lá

3. No Mac via Homebrew, use o brew

brew upgrade claude-code

Dependendo do cask que você instalou, pode ser brew upgrade claude-code@latest

O erro comum deste passo: achar que o Homebrew atualiza sozinho

Não atualiza

Homebrew NÃO faz auto-update do Claude Code, é manual

4. No Windows via WinGet, use o winget

winget upgrade Anthropic.ClaudeCode

O erro comum deste passo: mesmo caso do Homebrew

WinGet também não faz auto-update, você tem que chamar o comando na mão

5. Confirme a versão instalada

Depois de qualquer um dos caminhos acima, confere:

claude --version

Se o número mudou, deu certo

Se continua o mesmo mesmo depois do update, calma, isso tem explicação e eu resolvo na próxima seção

Cansou de rodar na mão? Ligue o auto-update do gerenciador

Homebrew e WinGet não se atualizam sozinhos por padrão, mas dá pra pedir pro Claude Code rodar o upgrade do gerenciador por você

Tem uma variável de ambiente que liga isso:

CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1

Com ela ativa, o Claude Code roda o upgrade em segundo plano e mostra um aviso de reinício quando termina

Bem de boa =)

Erros de versão no CLI e como resolver

Aqui mora a maior parte da dor de cabeça

Quase tudo vem de ter instalado por mais de um método

Atualizei, mas a versão continua a mesma

Esse é o clássico

A causa: você tem DOIS binários claude no PATH, um nativo e um do npm

O que aparece primeiro no PATH vence, então mesmo depois de atualizar um deles, o outro (mais velho) é o que roda

Parece que o update não pegou, mas ele pegou no binário errado

Como resolver: roda o diagnóstico pra enxergar o conflito

claude doctor

Ele mostra o tipo de instalação e o PATH, e aí fica claro qual binário está vencendo

Como prevenir: não instala por mais de um método

Escolhe um caminho (nativo OU npm OU gerenciador) e fica nele

Migrei pro binário nativo e meu launcher antigo quebrou

O CLI claude agora roda um binário nativo por plataforma em vez de JavaScript empacotado

Ou seja: o comando claude não invoca mais o Node

Se você tinha um launcher customizado apontando pro jeito antigo, ele pode atrapalhar depois dessa mudança

Como resolver: remove o launcher antigo e deixa o Claude Code gerenciar o launcher de novo

No Linux e no estilo Unix do Mac esse launcher fica em ~/.local/bin/claude:

rm ~/.local/bin/claude
claude update

Depois disso o claude update volta a cuidar do launcher sozinho

Se você está no Windows, o launcher não fica nesse caminho: roda o claude doctor primeiro pra ver onde está o binário e o estado da instalação antes de mexer em qualquer coisa

Como prevenir: se você não tem certeza se mexeu no launcher no passado, roda o claude doctor antes pra ver o estado atual

Problemas dentro da sessão (MCP morto, hooks lentos)

Às vezes o CLI está atualizado, mas algo trava DENTRO da sessão: um servidor MCP que morreu, um hook lento, a instalação meio bagunçada

Pra isso tem um comando de checkup que diagnostica e conserta esses problemas de dentro da própria sessão do Claude Code:

/doctor

O alias dele é /checkup, faz a mesma coisa

Como prevenir: de novo, o mesmo remédio de sempre, evitar instalar por mais de um método e manter uma instalação só

A maioria dos "erros de versão" some quando o ambiente está limpo

Conclusão

Atualizar o Claude Code vira um hábito curto de poucos comandos

claude doctor antes, pra ver como você instalou e se tem conflito de PATH

claude update pra forçar a versão mais recente na hora, ou o comando do seu gerenciador se você instalou por npm, Homebrew ou WinGet

claude --version pra confirmar que mudou

O próximo passo é manter UMA instalação só e checar o PATH toda vez que você trocar de método

É isso que evita aquela versão fantasma que parece travada mesmo depois do update

Simples, né? 🙂