Module 2.1 — Installing Claude Code

🖥️ System Requirements

Before you start, make sure your environment has what it needs. Node.js v18+ is the only mandatory requirement — everything else is optional but recommended.

✓ Ideal environment

✓Node.js v18 or later (LTS recommended)
✓npm v9+ (comes with Node.js) or Bun v1+
✓Terminal with color support (iTerm2, Warp, Windows Terminal)
✓Internet access for OAuth authentication
✓macOS 12+, Ubuntu 20.04+, or WSL2 on Windows

✗ Common problems

✗Node.js v16 or earlier — installation fails
✗Native Windows (cmd/PowerShell without WSL2) — limited compatibility
✗npm installed with sudo on Linux — broken permissions
✗Corporate network with an unconfigured proxy
✗Disk full — package installation fails silently

Verify versions before installing

# 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

💡 Tip: use nvm to manage versions

O nvm (Node Version Manager) lets you install and switch between Node.js versions without conflicts. Ideal if you work on multiple projects. Install with curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash and use nvm install --lts to the latest LTS version.

📦 Installation with npm (and Bun)

Installation takes a single command. The flag -g installs globally — the binary claude will be available in any directory on the system.

Install via npm

The standard and most reliable method

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

Alternative: install via Bun

Faster, ideal if you already use Bun in the project

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

Wait for completion

Installation takes 30–90 seconds, depending on the network.

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

Verify installation

Confirm that the binary is on the PATH

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

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

✅ Checking and testing

After installing, three commands confirm that everything is set up correctly. Run them in order—they test the installation, PATH, and basic functionality.

Post-installation verification checklist

# 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"

📊 What to expect

claude --version → prints semantic version (e.g., 1.2.3)
which claude → shows the binary's absolute path
claude --help → lists flags: --print, --resume, --version, --model
claude (without flags) → opens an interactive REPL or starts authentication

🔄 Updating Claude Code

Claude Code receives frequent updates. New versions bring support for newer models, bug fixes and features. Updating takes less than 1 minute.

💡 When to update

Update whenever: a message about an outdated version appears in the terminal, Anthropic releases a new model (Claude 4, etc.), or a feature you want isn't available in your version.

Update commands

# 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

✓ Update best practices

✓Update weekly in active projects
✓Read the changelog before updating in production
✓Test in dev before updating the CI environment

✗ Avoid

✗Update during an important active session
✗Pinning an old version without justification
✗Ignore breaking changes in the changelog

🖱️ Guide by Operating System

Each OS has its own installation details. macOS and Linux are natively supported. Windows works best with WSL2.

🍎 macOS

# via Homebrew:

brew install node

# install Claude Code:

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

No PATH issues with Homebrew. Best overall experience.

🐧 Linux

# via nvm (recommended):

nvm install --lts

nvm use --lts

# install:

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

Avoid apt install nodejs — the version is usually outdated.

🪟 Windows (WSL2)

# install WSL2:

wsl --install

# inside WSL2 (Ubuntu):

nvm install --lts

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

Windows Terminal + WSL2 = an experience almost identical to Linux.

💡 Tip: Windows Terminal is required

If you use Windows, install the Windows Terminal (free in the Microsoft Store). cmd.exe and the legacy PowerShell don't render Claude Code's colors and UI correctly. With Windows Terminal + WSL2, the experience is complete.

🔧 Troubleshooting: Common Errors

The 5 most common installation errors have straightforward solutions. Read the error in the terminal, identify the type, and apply the fix.

EACCES: permission denied

npm doesn’t have permission to write to the global folder

# 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

Installation succeeded, but PATH doesn't include the global npm directory

# 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

Incompatible Node.js version (v16 or earlier)

# 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

⚠️ Never use sudo with npm install -g

Run sudo npm install -g fixes the immediate EACCES error but creates bigger problems: files owned by root, conflicts during future updates, and security risks. Use nvm or configure the npm global directory as described above.

✅ Module 2.1 Summary

✓

Node.js v18+ is the only mandatory requirement

✓

npm install -g @anthropic-ai/claude-code — the installation command

✓

claude --version confirms successful installation

✓

EACCES? Use nvm, never sudo

✓

Windows? WSL2 + Windows Terminal is the right combination

Next Module:

2.2 — Authentication and first use: run claude, login, API key vs subscription, and your first real commands.

← Back to Track 2 Next Module →