Guia de campo do Claude Code em português

Instalar o Claude Code no Mac e no Linux: um comando, e o PATH quando ele falha

No Mac e no Linux, instalar o Claude Code é uma linha no terminal. O que dá trabalho é o depois: o terminal que não acha o claude, o Homebrew que não se atualiza, o servidor pequeno que mata a instalação no meio. Abaixo, cada caminho com os comandos da doc oficial em português (lida em 18/10/2026) e da seção 1.1 do guia (p. 8), que está na amostra grátis.

Antes: o seu sistema roda o Claude Code?

Item	O que a doc pede
Mac	macOS 13.0 ou mais novo
Linux	Ubuntu 20.04+, Debian 10+ ou Alpine Linux 3.19+
Máquina	4 GB de RAM ou mais, processador x64 ou ARM64
Rede	Internet obrigatória, num dos países atendidos pela Anthropic
Shell	Bash ou Zsh

Precisa de internet porque o modelo roda nos servidores da Anthropic, não no seu computador (p. 8). E precisa de uma conta: assinatura do claude.ai (Pro, Max, Team ou Enterprise), Claude Console ou provedor de nuvem; o plano gratuito não inclui o Claude Code (p. 10).

O jeito recomendado: o instalador nativo

Abra o Terminal (no Mac, pelo Spotlight; no Linux, o do seu sistema) e cole:

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

O instalador não mostra progresso enquanto baixa. Quando terminar, abra uma janela nova do terminal e confira:

claude --version

A resposta é um número de versão seguido de "(Claude Code)". O executável fica em ~/.local/bin/claude, que a doc descreve como um link para ~/.local/share/claude/versions/, e a instalação nativa se atualiza sozinha, em segundo plano. É um executável único, sem Node.js (p. 8). A mesma linha serve no WSL, o Linux dentro do Windows (veja PowerShell ou WSL).

Depois, entre na pasta do projeto e rode claude: na primeira vez, o navegador abre para o login. O que fazer se o login travar está em login, chave de API e erros.

Homebrew, apt, dnf e apk: quando usar e o que muda

No Mac, o Homebrew também instala:

brew install --cask claude-code

A diferença que pesa: por padrão, o Homebrew não atualiza o Claude Code. Você atualiza à mão com brew upgrade claude-code (ou brew upgrade claude-code@latest, se foi esse o cask instalado); com a variável CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE em 1, o próprio Claude Code roda a atualização em segundo plano. Há dois casks: claude-code segue o canal estável, que fica "cerca de uma semana atrás" e pula versões com regressões importantes; claude-code@latest recebe cada versão assim que sai. O Homebrew guarda as versões antigas no disco; brew cleanup libera o espaço.

No Linux, a Anthropic publica repositórios assinados para apt (Debian e Ubuntu), dnf (Fedora e RHEL) e apk (Alpine). No Debian e no Ubuntu, a doc instala o canal estável assim (se faltar curl ou gpg, antes sudo apt install curl gnupg):

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

A doc pede para conferir antes de seguir que a chave baixada é da Anthropic (gpg --show-keys /etc/apt/keyrings/claude-code.asc, que tem de mostrar a impressão digital 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE). No Fedora e no RHEL, o repositório entra em /etc/yum.repos.d/claude-code.repo e a instalação é sudo dnf install claude-code; os comandos completos de dnf e apk estão na página de configuração da doc. Pelo gerenciador do sistema, o Claude Code também não se atualiza sozinho: sudo apt update && sudo apt upgrade claude-code, ou sudo dnf upgrade claude-code.

Método	Atualiza sozinho?	Para quem
Nativo (`install.sh`)	Sim, em segundo plano	Quase todo mundo
Homebrew	Não, por padrão: `brew upgrade claude-code`	Quem já gerencia tudo pelo brew
apt, dnf, apk	Não: pelo gerenciador do sistema	Servidor com atualização centralizada

No Alpine, o instalador nativo precisa de pacotes que o sistema não traz: a doc manda instalar apk add bash curl libgcc libstdc++ ripgrep e definir USE_BUILTIN_RIPGREP=0.

"command not found: claude": o PATH

A instalação terminou e o terminal não acha o programa. A mensagem muda conforme o sistema:

Sistema	Mensagem
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`

Quase sempre a pasta ~/.local/bin não está no PATH, a lista de pastas onde o terminal procura programas. O instalador até avisa, em "Setup notes:", mas não muda o PATH por você. Primeiro, confira se o programa está lá e se a pasta está no PATH:

ls -la ~/.local/bin/claude
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

Se a primeira linha lista o arquivo e a segunda não imprime nada, acrescente a pasta ao arquivo de configuração do seu shell. No zsh, o padrão do Mac:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

No bash do Linux, troque ~/.zshrc por ~/.bashrc; no bash do Mac, por ~/.bash_profile (p. 9). A doc explica o porquê: o Terminal do Mac abre o bash como shell de login, que ignora o ~/.bashrc; se você já tem ~/.bash_login ou ~/.profile e nenhum ~/.bash_profile, a linha vai nesse arquivo. Feito isso, claude --version numa janela nova. Se ainda falhar, a doc aponta três culpados: a janela é anterior à mudança (o terminal de dentro do VS Code herda o PATH do editor, então feche e reabra o editor inteiro), a linha não foi salva, ou ela foi para o arquivo de outro shell (echo $0 diz qual shell você usa). E se o echo responder permission denied, o arquivo é de outro usuário (sudo chown $(whoami) ~/.zshrc) ou está só para leitura (chmod u+w ~/.zshrc).

Outros erros de instalação

Mensagem	Causa	Conserto
syntax error near unexpected token `<'	O endereço devolveu uma página da web, não o script: rede, proxy ou falha passageira	Tente de novo em alguns minutos; no Mac, o Homebrew é a alternativa. Se o erro citar "App unavailable in region", o Claude Code não está disponível no seu país, e nenhum instalador resolve
`curl: (22) The requested URL returned error: 403`	A mesma causa, ou proxy e firewall da empresa	Confira a rede antes de trocar de instalador
`Killed` (código de saída 137)	Servidor pequeno ficou sem memória: a instalação precisa de cerca de 512 MB livres	Feche processos, crie swap ou use uma máquina maior; o Claude Code pede pelo menos 4 GB de RAM
`dyld: Symbol not found` ou `Abort trap: 6`	macOS mais antigo que o 13.0	Atualize o macOS; o Homebrew baixa o mesmo programa e não resolve

Conferir que ficou certo

Fora da sessão, claude doctor mostra o método de instalação, qual executável respondeu e se as atualizações automáticas estão ligadas. Com duas instalações na máquina (a nativa e outra por npm ou Homebrew), roda a que vem primeiro no PATH, e a linha Path do relatório diz qual foi (p. 14). Dentro da sessão, /status mostra versão, modelo e conta. Para manter em dia, veja como atualizar o Claude Code.

Fora do livro: code.claude.com/docs/pt/setup e /docs/pt/troubleshoot-install, lidas em 18/10/2026.