Como instalar o Claude Code no macOS e no Linux (curl, Homebrew e apt)

Q: Como desinstalo?

Na instalação nativa, apague o link e as versões com rm -f ~/.local/bin/claude e rm -rf ~/.local/share/claude. As configurações e o histórico ficam em ~/.claude e ~/.claude.json. Apague esses dois também se quiser zerar tudo.

Pra instalar o Claude Code no macOS ou no Linux, abra o terminal e rode curl -fsSL https://claude.ai/install.sh | bash. O instalador nativo não pede sudo, coloca o claude em ~/.local/bin e se atualiza sozinho. Se depois o terminal disser que o comando não existe, falta pôr ~/.local/bin no PATH. Os requisitos são macOS 13.0 ou mais novo, ou Ubuntu 20.04+, Debian 10+ ou Alpine Linux 3.19+, com 4 GB de RAM e processador x64 ou ARM64. No Mac também dá pra instalar pelo Homebrew, e no Linux, pelo apt, dnf ou apk.

Este post é um dos guias práticos do guia de Claude Code. Os passos seguem a documentação de instalação e o guia de solução de problemas de instalação oficiais. As saídas mostradas foram capturadas em 18 de outubro de 2026 em containers limpos de Ubuntu 24.04 e Alpine 3.22 (x64), sem login, com Claude Code 2.1.302. Não rodamos nada num Mac. Os comandos de macOS e de Homebrew vêm da documentação. No Windows, o caminho é outro, e está em Como instalar o Claude Code no Windows.

Escolha o método de instalação

Método	Comando	Atualiza sozinho?	Quando usar
Instalador nativo	`curl -fsSL https://claude.ai/install.sh \| bash`	Sim, em segundo plano	O padrão, recomendado pela Anthropic, no macOS, no Linux e no WSL
Homebrew (macOS)	`brew install --cask claude-code`	Não, por padrão	Você já gerencia as ferramentas do Mac pelo Homebrew
apt, dnf ou apk	`sudo apt install claude-code`, depois de registrar o repositório	Não. A versão nova chega no upgrade do sistema	Servidores e máquinas gerenciadas, com assinatura conferida pelo gerenciador de pacotes
npm	`npm install -g @anthropic-ai/claude-code`	Sim, se a pasta global do npm aceitar escrita	A instalação precisa passar pelo npm. Exige Node.js 22 ou mais novo

Os quatro entregam o mesmo binário nativo. Escolha um só. Duas instalações na mesma máquina podem causar versão trocada e comportamento inesperado, e o which -a claude mostra quantas existem no seu PATH.

Confira os requisitos antes de instalar

A documentação pede macOS 13.0 ou mais novo, ou então Ubuntu 20.04+, Debian 10+ ou Alpine Linux 3.19+. Em qualquer um, são 4 GB de RAM, processador x64 ou ARM64, shell Bash ou Zsh e conexão com a internet. No Linux, duas linhas mostram a arquitetura e a biblioteca C:

uname -m
ldd --version 2>&1 | head -1

No teste, deram x86_64 e ldd (Ubuntu GLIBC 2.39-0ubuntu8.9) 2.39. Se a segunda linha fala em musl, você está numa distro como o Alpine, que pede pacotes extras (seção própria mais abaixo). No macOS, confira a versão em menu Apple > Sobre Este Mac.

A outra checagem é a conta. O Claude Code exige plano Pro, Max, Team, Enterprise ou conta do Console. O plano gratuito do claude.ai não inclui acesso. Também dá pra usar via Amazon Bedrock, Agent Platform do Google Cloud ou Microsoft Foundry.

Instale com o instalador nativo

Abra o terminal. No macOS, aperte Cmd + Espaço, digite Terminal e tecle Enter. Na maioria das distros Linux, o atalho é Ctrl + Alt + T. Depois rode:

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

O comando não mostra progresso enquanto baixa. No teste, num Ubuntu 24.04 limpo e com um usuário comum, sem sudo, ele levou 24 segundos e imprimiu:

Setting up Claude Code...

Checking installation status...
Installing Claude Code native build latest...
Setting up launcher and shell integration...
⚠ Setup notes:
  ● Native installation exists but ~/.local/bin is not in your PATH. Run:

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

✔ Claude Code successfully installed!

  Version: 2.1.302

  Location: ~/.local/bin/claude


  Next: Run claude --help to get started

⚠ Setup notes:
  ● Native installation exists but ~/.local/bin is not in your PATH. Run:

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


✅ Installation complete!

O instalador criou ~/.local/bin/claude, um link para ~/.local/share/claude/versions/2.1.302. Ele não mexe no PATH. O Setup notes, que aparece duas vezes na saída, só imprime o comando que resolve. Tudo fica na sua pasta pessoal, então não precisa de sudo.

Pra instalar o canal estável (em geral cerca de uma semana atrás da versão mais nova, pulando versões com regressões graves) ou uma versão específica, passe o argumento pro bash:

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

No dia do teste, stable instalou a 2.1.292, enquanto o canal padrão (latest) estava na 2.1.302. O canal que você escolhe na instalação vira o padrão das atualizações automáticas.

Ponha `~/.local/bin` no PATH

Primeiro confira se a pasta já está no PATH:

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

Se não sair nada, a pasta não está. Acrescente a linha no arquivo de configuração do seu shell e recarregue o arquivo. No Zsh, o shell padrão do macOS:

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

No Bash, o padrão da maioria das distros Linux:

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

No Bash do macOS, use o ~/.bash_profile. O Terminal do macOS abre o Bash como shell de login, e o shell de login ignora o ~/.bashrc:

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

Depois abra um terminal novo, porque uma janela que já estava aberta guarda o PATH antigo. Um terminal dentro do editor herda o PATH do editor, então feche e abra o editor também. No Ubuntu do teste, o ~/.profile padrão já põe ~/.local/bin no PATH quando a pasta existe, e um shell de login novo achou o claude sem nenhuma mudança. O instalador avisa mesmo assim, porque o shell onde você rodou o comando ainda não tem a pasta.

Ou instale com Homebrew (macOS)

brew install --cask claude-code

A cask claude-code segue o canal estável. Pra receber cada versão assim que sai, instale a claude-code@latest. A instalação pelo Homebrew não se atualiza sozinha. Rode brew upgrade claude-code (ou brew upgrade claude-code@latest, conforme a cask) de vez em quando, ou defina CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 pro Claude Code rodar o upgrade por você em segundo plano. O Homebrew guarda as versões antigas no disco, e o brew cleanup libera esse espaço.

Se o Homebrew responder Error: Cask 'claude-code' is unavailable: No Cask with this name exists, o índice local está velho. Rode brew update e tente de novo.

Ou instale com apt, dnf ou apk

A Anthropic publica repositórios assinados pra Debian e Ubuntu (apt), Fedora e RHEL (dnf) e Alpine (apk), cada um com os canais stable e latest. Esse caminho pede sudo (ou root, no Alpine), e a atualização vem pelo upgrade normal do sistema, não pelo Claude Code. No apt, comece baixando a chave e conferindo a impressão digital:

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
gpg --show-keys /etc/apt/keyrings/claude-code.asc

A impressão digital precisa ser 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. Se o curl ou o gpg não existirem na máquina, instale os dois antes com sudo apt install curl gnupg. Depois registre o repositório do canal stable e instale:

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

No teste, num Ubuntu 24.04, o apt instalou a 2.1.292 em /usr/bin/claude, que já está no PATH. O claude doctor mostrou Running: package-manager (2.1.292), Package manager: deb e Auto-updates: Managed by package manager. Pra atualizar depois, rode sudo apt update && sudo apt upgrade claude-code. Pra trocar pro canal latest, o caminho da URL e o nome da suíte mudam juntos, e a linha termina em apt/latest latest main.

No Fedora e no RHEL, o repositório entra num arquivo .repo:

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

Na primeira instalação, o dnf pede pra você confirmar a impressão digital da chave, que precisa ser 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE. Pra atualizar, rode sudo dnf upgrade claude-code. Não testamos o dnf. Os comandos do repositório apk estão na documentação.

No Alpine, instale as dependências antes

O Alpine e outras distros baseadas em musl não trazem bash nem curl, e o comando de instalação falha com not found sem eles. O Claude Code também precisa de libgcc, libstdc++ e ripgrep pra rodar. Instale tudo com o apk:

apk add bash curl libgcc libstdc++ ripgrep

Com esses pacotes, o instalador nativo funcionou no Alpine 3.22 do teste e instalou a 2.1.302. Falta um ajuste. Diga ao Claude Code pra usar o ripgrep do sistema, no settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

O ripgrep fica no repositório community do Alpine. Se o apk não achar o pacote, acrescente o community da sua versão do Alpine em /etc/apk/repositories, rode apk update e repita o apk add.

Use o npm só se precisar

O pacote npm instala o mesmo binário nativo, que chega por uma dependência opcional de cada plataforma. Ele exige Node.js 22 ou mais novo, mas o claude instalado não usa o Node pra rodar.

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

Não use sudo npm install -g. A documentação avisa que isso causa problemas de permissão e riscos de segurança. Pra atualizar, rode npm install -g @anthropic-ai/claude-code@latest. O npm update -g respeita a faixa de versão da instalação original e pode não chegar à versão mais nova.

Verifique a instalação e faça login

Num terminal novo, rode:

claude --version
claude doctor

O primeiro imprime 2.1.302 (Claude Code) (ou a sua versão). O claude doctor funciona antes do login e saiu com código 0. Saída real, sem conta conectada:

Claude Code doctor

Running: native (2.1.302)
Commit: 2ef144e6f98c
Platform: linux-x64
Path: /home/dev/.local/share/claude/versions/2.1.302
Config install method: native
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: none recorded
Managed settings (remote): not fetched — no usable credentials for the settings fetch
Organization policy: not fetched: no API key or claude.ai sign-in for the policy lookup (apiKeyHelper keys are not used for it)

Remote Control
Remote Control requires a claude.ai subscription. Run claude auth login to sign in with your claude.ai account.
- Not signed in to claude.ai
...

No installation issues found.

A linha que importa é No installation issues found.. As linhas de Remote Control e de política só dizem que você ainda não fez login. O campo Path aponta pra pasta da versão, em ~/.local/share/claude/versions/, e não pro link em ~/.local/bin.

Depois entre na pasta do projeto e rode claude. O login abre no navegador. Sem login, claude -p "oi" saiu com código 1 e Not logged in · Please run /login. Por SSH, num container ou numa máquina sem navegador, o navegador abre em outro computador e não consegue voltar pro terminal. Nesse caso, a página mostra um código depois que você entra na conta. Cole esse código no prompt Paste code here if prompted. Se colar no prompt não funcionar, use claude auth login, que lê o código da entrada padrão.

No macOS, o Claude Code guarda a credencial no Keychain. Quando o Keychain recusa a escrita (bloqueado numa sessão SSH, por exemplo), o login vai pra um arquivo em texto puro, ~/.claude/.credentials.json. O claude doctor avisa com macOS Keychain is not writable, e security unlock-keychain ~/Library/Keychains/login.keychain-db desbloqueia o Keychain.

Como usamos na Capiva

Com o Claude Code instalado, o próximo passo aqui é o harness. O capivaOS entra como plugin. Em máquina sem sessão interativa, como CI ou servidor, a instalação são dois comandos (README):

claude plugin marketplace add iB2/capivaOS
claude plugin install capiva@capiva --scope project

Os hooks do capivaOS precisam de Python 3 acessível como python3, python ou py, e se desligam quando não acham nenhum dos três. Todo claude -p num pipeline também precisa de credencial no ambiente. Sem ela, o resultado é o mesmo Not logged in do teste acima.

Checklist de troubleshooting

[ ] zsh: command not found: claude ou bash: claude: command not found depois de instalar. A pasta ~/.local/bin não está no PATH, ou o terminal é anterior à mudança. Siga a seção do PATH e abra um terminal novo.
[ ] zsh: permission denied: /Users/you/.zshrc (ou o mesmo com ~/.bashrc). Seu usuário não pode escrever no arquivo, e nada foi salvo. Veja o dono com ls -l ~/.zshrc. Se o dono for outro usuário, rode sudo chown $(whoami) ~/.zshrc. Se for você, rode chmod u+w ~/.zshrc.
[ ] syntax error near unexpected token '<'. O download trouxe uma página HTML em vez do script. Espere alguns minutos e tente de novo, ou use o Homebrew ou o apt. Se a saída citar App unavailable in region, o Claude Code não está disponível no seu país.
[ ] curl: (22) The requested URL returned error: 403. Um proxy ou filtro de rede está bloqueando o download, ou o país não é atendido. Teste o acesso com curl -sI https://downloads.claude.ai/claude-code-releases/latest. A primeira linha precisa mostrar 200.
[ ] curl: (23) ou curl: (56) Failure writing output to destination. O Bash não recebeu o script inteiro. Confira a conexão e rode o comando de novo.
[ ] Killed ou Installation was killed before it could finish (exit code 137). Faltou memória. A instalação precisa de cerca de 512 MB livres. Feche processos ou crie um arquivo de swap, o que é comum num servidor Linux remoto com pouca memória.
[ ] A instalação trava num container Docker. Rodado como root a partir de /, o instalador varre o sistema de arquivos inteiro. Defina um WORKDIR, como /tmp, antes do RUN.
[ ] Error loading shared library libstdc++.so.6. O instalador baixou a variante errada do binário, de musl num sistema glibc. Confira com ldd --version 2>&1 | head -1. No Alpine, instale libgcc, libstdc++ e ripgrep.
[ ] Illegal instruction. Ou a arquitetura está errada (confira com uname -m), ou a CPU não tem AVX, o que acontece em boa parte dos processadores de antes de 2013 e em VMs que não repassam AVX. Se grep -m1 -ow avx /proc/cpuinfo não imprimir nada, falta AVX. Nenhum outro instalador resolve, porque todos baixam o mesmo binário.
[ ] dyld: Symbol not found, dyld: cannot load ou Abort trap: 6 no macOS. O macOS é anterior ao 13.0. Atualize o sistema. O Homebrew baixa o mesmo binário e não resolve.
[ ] NO_PUBKEY BAA929FF1A7ECACE no apt update. O download da chave falhou. Repita o curl da chave e confira com gpg --show-keys.

Perguntas frequentes

Preciso de sudo pra instalar?▼

Não pro instalador nativo, que escreve só na sua pasta pessoal. O apt e o dnf pedem sudo. No npm, a documentação manda nunca usar sudo.

Preciso de Node.js?▼

Só pra instalar pelo npm, que exige Node.js 22 ou mais novo. O instalador nativo, o Homebrew e os pacotes do Linux não usam o Node.

Como atualizo o Claude Code?▼

A instalação nativa se atualiza sozinha em segundo plano, e claude update aplica a versão nova na hora. Homebrew, apt, dnf e apk atualizam pelo próprio gerenciador de pacotes.

Como desinstalo?▼

Na instalação nativa, apague o link e as versões com rm -f ~/.local/bin/claude e rm -rf ~/.local/share/claude. As configurações e o histórico ficam em ~/.claude e ~/.claude.json. Apague esses dois também se quiser zerar tudo.

Existe versão com interface gráfica?▼

Existe o app Desktop do Claude Code, que dispensa o terminal, pra macOS e Linux. No Linux, ele se instala pelo apt.

Como instalar o Claude Code no macOS e no Linux: instalador nativo, Homebrew, apt e PATH (e os erros mais comuns)

Escolha o método de instalação

Confira os requisitos antes de instalar

Instale com o instalador nativo

Ponha `~/.local/bin` no PATH

Ou instale com Homebrew (macOS)

Ou instale com apt, dnf ou apk

No Alpine, instale as dependências antes

Use o npm só se precisar

Verifique a instalação e faça login

Como usamos na Capiva

Checklist de troubleshooting

Perguntas frequentes

Leia também

Escolha o método de instalação

Confira os requisitos antes de instalar

Instale com o instalador nativo

Ponha ~/.local/bin no PATH

Ou instale com Homebrew (macOS)

Ou instale com apt, dnf ou apk

No Alpine, instale as dependências antes

Use o npm só se precisar

Verifique a instalação e faça login

Como usamos na Capiva

Checklist de troubleshooting

Perguntas frequentes

Leia também

Ponha `~/.local/bin` no PATH