Módulo 2.1 — Instalando Claude Code

🖥️ Requisitos do sistema

Antes de instalar, confirme que seu ambiente tem o que é necessário. Node.js v18+ é o único requisito obrigatório — tudo mais é opcional mas recomendado.

✓ Ambiente ideal

✓Node.js v18 ou superior (LTS recomendado)
✓npm v9+ (vem com Node.js) ou Bun v1+
✓Terminal com suporte a cores (iTerm2, Warp, Windows Terminal)
✓Acesso à internet para autenticação OAuth
✓macOS 12+, Ubuntu 20.04+, ou WSL2 no Windows

✗ Problemas comuns

✗Node.js v16 ou anterior — instalação falha
✗Windows nativo (cmd/PowerShell sem WSL2) — compatibilidade limitada
✗npm instalado com sudo em Linux — permissões quebradas
✗Rede corporativa com proxy não configurado
✗Disco cheio — instalação de pacotes falha silenciosamente

Verificar versões antes de instalar

# Verificar Node.js
node -v
# Output esperado: v18.x.x ou superior

# Verificar npm
npm -v
# Output esperado: 9.x.x ou superior

# Alternativa: verificar Bun
bun -v
# Output esperado: 1.x.x

# Se Node.js não estiver instalado (macOS com Homebrew):
brew install node

# Se Node.js não estiver instalado (Ubuntu/Debian):
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

💡 Dica: use nvm para gerenciar versões

O nvm (Node Version Manager) permite instalar e trocar entre versões do Node.js sem conflitos. Ideal para quem trabalha com múltiplos projetos. Instale com curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash e use nvm install --lts para a versão LTS mais recente.

📦 Instalação com npm (e Bun)

A instalação é um único comando. A flag -g instala globalmente — o binário claude ficará disponível em qualquer diretório do sistema.

Instalar via npm

O método padrão e mais confiável

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

Alternativa: instalar via Bun

Mais rápido, ideal se você já usa Bun no projeto

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

Aguardar conclusão

A instalação leva 30–90 segundos dependendo da rede

# Output esperado durante instalação:
added 247 packages in 45s
+ @anthropic-ai/claude-code@1.x.x

Verificar instalação

Confirmar que o binário está no PATH

claude --version
# Output: Claude Code 1.x.x

which claude
# Output: /usr/local/bin/claude (ou similar)

✅ Verificando e testando

Após instalar, três comandos confirmam que tudo está correto. Execute na ordem — eles testam instalação, PATH e funcionamento básico.

Checklist de verificação pós-instalação

# 1. Versão instalada
claude --version
# ✓ Claude Code 1.x.x

# 2. Caminho do binário
which claude
# ✓ /usr/local/bin/claude
# ou: /home/user/.local/bin/claude (Linux com nvm)

# 3. Help básico (confirma binário funcional)
claude --help
# ✓ Lista de flags e subcomandos

# 4. Se 'claude' não for encontrado:
# Verificar se ~/.npm/bin está no PATH
echo $PATH | grep npm

# Adicionar ao .bashrc ou .zshrc se necessário:
export PATH="$HOME/.npm/bin:$PATH"

📊 O que esperar

claude --version → imprime versão semântica (ex: 1.2.3)
which claude → mostra caminho absoluto do binário
claude --help → lista flags: --print, --resume, --version, --model
claude (sem flags) → abre REPL interativo ou inicia autenticação

🔄 Atualizando o Claude Code

O Claude Code recebe atualizações frequentes. Novas versões trazem suporte a modelos mais recentes, correções de bugs e features. Atualizar leva menos de 1 minuto.

💡 Quando atualizar

Atualize sempre que: aparecer mensagem de versão desatualizada no terminal, sair um modelo novo da Anthropic (Claude 4, etc.) ou uma feature que você quer não aparecer na sua versão.

Comandos de atualização

# Atualizar via npm
npm update -g @anthropic-ai/claude-code

# Ou reinstalar para garantir última versão
npm install -g @anthropic-ai/claude-code@latest

# Atualizar via Bun
bun update -g @anthropic-ai/claude-code

# Verificar versão atual vs mais recente
npm outdated -g @anthropic-ai/claude-code

# Verificar versão após atualização
claude --version

✓ Boas práticas de atualização

✓Atualizar semanalmente em projetos ativos
✓Ler o changelog antes de atualizar em produção
✓Testar em dev antes de atualizar ambiente de CI

✗ Evitar

✗Atualizar durante uma sessão ativa importante
✗Fixar versão antiga sem justificativa
✗Ignorar breaking changes no changelog

🖱️ Guia por sistema operacional

Cada OS tem particularidades de instalação. macOS e Linux são nativamente suportados. Windows funciona melhor com WSL2.

🍎 macOS

# via Homebrew:

brew install node

# instalar Claude Code:

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

Sem problemas de PATH com Homebrew. Melhor experiência geral.

🐧 Linux

# via nvm (recomendado):

nvm install --lts

nvm use --lts

# instalar:

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

Evite apt install nodejs — versão geralmente antiga.

🪟 Windows (WSL2)

# instalar WSL2:

wsl --install

# dentro do WSL2 (Ubuntu):

nvm install --lts

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

Windows Terminal + WSL2 = experiência quase idêntica ao Linux.

💡 Dica: Windows Terminal é obrigatório

Se você usa Windows, instale o Windows Terminal (gratuito na Microsoft Store). O cmd.exe e o PowerShell antigo não renderizam as cores e UI do Claude Code corretamente. Com Windows Terminal + WSL2 a experiência é completa.

🔧 Diagnóstico: erros comuns

Os 5 erros mais frequentes na instalação têm soluções diretas. Leia o erro no terminal, identifique o tipo e aplique o fix.

EACCES: permission denied

npm não tem permissão para escrever na pasta global

# Solução 1: configurar npm para usar diretório do usuário
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Solução 2: usar nvm (recomendado — evita sudo)
nvm install --lts && npm i -g @anthropic-ai/claude-code

command not found: claude

Instalação ok mas PATH não inclui a pasta do npm global

# Encontrar onde o npm instala globalmente
npm config get prefix
# Ex: /home/user/.npm-global

# Adicionar ao PATH (substituir pelo caminho real)
export PATH="/home/user/.npm-global/bin:$PATH"

# Persistir no .bashrc ou .zshrc
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc

engine "node" unsupported / ENOTSUP

Node.js versão incompatível (v16 ou inferior)

# Atualizar Node.js com nvm
nvm install 20  # LTS atual
nvm use 20
nvm alias default 20

# Verificar e reinstalar
node -v  # deve mostrar v20.x.x
npm install -g @anthropic-ai/claude-code

⚠️ Nunca use sudo com npm install -g

Rodar sudo npm install -g corrige o EACCES imediato mas cria problemas maiores: arquivos com ownership de root, conflitos em atualizações futuras e riscos de segurança. Use nvm ou configure a pasta global do npm conforme acima.

✅ Resumo do Módulo 2.1

✓

Node.js v18+ é o único requisito obrigatório

✓

npm install -g @anthropic-ai/claude-code — o comando de instalação

✓

claude --version confirma instalação bem-sucedida

✓

EACCES? Use nvm, nunca sudo

✓

Windows? WSL2 + Windows Terminal é a combinação certa

Próximo Módulo:

2.2 — Autenticação e primeiro uso: rodar claude, login, API key vs assinatura e seus primeiros comandos reais.

← Voltar para Trilha 2 Próximo Módulo →