Claude Code Installation Guide

Quick Reference

Method	Command	Auto-Update	Requires Node.js
Native Installer (Recommended)	curl -fsSL https://claude.ai/install.sh | bash	✅ Yes	❌ No
Homebrew	brew install --cask claude-code	⚠️ Manual	❌ No
npm	npm install -g @anthropic-ai/claude-code	⚠️ Manual	✅ Yes (18+)

Installation Methods

Option 1: Native Installer (Recommended)

macOS / Linux / WSL:

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash

# Verify installation
claude --version

Windows (PowerShell - Run as Administrator):

irm https://claude.ai/install.ps1 | iex
claude --version

Benefits:

• No Node.js dependency
• Automatic background updates
• Simplest installation
• Best performance

Installation Location:

• macOS/Linux: ~/.local/bin/claude
• Windows: %USERPROFILE%\.local\bin\claude.exe

---

Option 2: Homebrew (macOS)

# Install Claude Code
brew install --cask claude-code

# Verify installation
claude --version

# Manual updates required
brew upgrade claude-code

Benefits:

• Integrated with Homebrew workflow
• Clean uninstallation
• No Node.js required

Installation Location:

• Intel Macs: /usr/local/bin/claude
• Apple Silicon: /opt/homebrew/bin/claude

Important: Homebrew installations do NOT auto-update. Run brew upgrade claude-code periodically.

---

Option 3: npm (Requires Node.js 18+)

# Install globally
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

Prerequisites:

# Check Node.js version (must be 18+)
node --version

# Install Node.js if needed (macOS)
brew install node

# Install Node.js if needed (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Known Issue on macOS with Homebrew Node: If you see "command not found" after npm install, the symlink may be incorrect. Fix:

# Method 1: Fix PATH
echo 'export PATH="$(npm H.P.009-CONFIG get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Method 2: Use native installer instead (recommended)
npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

Benefits:

• Control over package versions
• Familiar for Node.js developers
• Can install specific versions: npm install -g @anthropic-ai/claude-code@2.1.12

Drawbacks:

• Requires Node.js runtime
• Manual updates: npm update -g @anthropic-ai/claude-code
• PATH H.P.009-CONFIGuration issues on some systems

---

System Requirements

• macOS: 13.0+ (Ventura or later)
• Linux: Ubuntu 20.04+ / Debian 10+ (requires libgcc, libstdc++, ripgrep)
• Windows: 10+ (WSL 1/2, Git for Windows, or native PowerShell)
• Node.js: 18.0+ (only for npm installation)

---

Post-Installation

1. Verify Installation

# Check version
claude --version

# Run diagnostics
claude doctor

Expected output:

Claude Code v2.1.12
Installation type: native

2. Authenticate

# Interactive login (recommended)
claude auth login

# Or set API key via environment variable
export ANTHROPIC_API_KEY="sk-ant-..."

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc

Get your API key from: https://console.anthropic.com/settings/keys

New users: Free API credits available for testing.

3. Initialize Project

# Navigate to project directory
cd ~/my-project

# Initialize Claude Code
claude init

# Start interactive session
claude chat

# Or run one-off command
claude "Create a React component for a todo list"

---

Troubleshooting

Command Not Found

Symptom: claude: command not found

Solution:

# Check if binary exists
ls ~/.local/bin/claude || ls ~/.claude/bin/claude

# Add to PATH (choose one based on where binary is located)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

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

# For zsh users, use ~/.zshrc instead of ~/.bashrc

Permission Errors (npm installation)

Never use sudo npm install -g

Instead, H.P.009-CONFIGure npm for user-level installations:

# Create user npm directory
mkdir -p ~/.npm-global

# Configure npm to use it
npm H.P.009-CONFIG set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall Claude Code
npm install -g @anthropic-ai/claude-code

Incorrect Symlink (macOS + Homebrew Node + npm)

Symptom: claude command exists but fails to execute

Solution:

# Check current symlink
ls -la /opt/homebrew/bin/claude

# If it points to .../lib/cli.js instead of .../bin/claude, recreate:
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# Or switch to native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash

Updates Not Working

Native installer: Auto-updates in background. Check with claude --version.

Homebrew: Manual updates required:

brew upgrade claude-code

npm: Manual updates required:

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

---

Uninstallation

Native Installer

macOS / Linux / WSL:

# Remove binary
rm -rf ~/.local/bin/claude
rm -rf ~/.local/share/claude

# Remove H.P.009-CONFIGuration (optional - deletes settings and history)
rm -rf ~/.claude
rm ~/.claude.json

Windows:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

# Remove H.P.009-CONFIGuration (optional)
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

Homebrew

brew uninstall --cask claude-code

# Remove H.P.009-CONFIGuration (optional)
rm -rf ~/.claude
rm ~/.claude.json

npm

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

# Remove H.P.009-CONFIGuration (optional)
rm -rf ~/.claude
rm ~/.claude.json

---

IDE Integration

Claude Code integrates with popular IDEs:

• VS Code: Install Claude Code extension from marketplace
• JetBrains IDEs: Install plugin for IntelliJ, WebStorm, PyCharm
• Vim/Neovim: LSP protocol integration
• Emacs: claude-mode package

See: https://code.claude.com/docs for integration guides

---

Recommendation Matrix

Use Case	Recommended Method
First-time user	Native installer
macOS with Homebrew workflow	Homebrew
Node.js developer	npm (but native is still easier)
Windows user	Native PowerShell script or WSL
Linux server	Native installer
Need specific version	npm or native with version flag

Bottom Line: Use the native installer unless you have a specific reason not to.

---

Next Steps

1. ✅ Install Claude Code
2. ✅ Authenticate with API key
3. ✅ Run claude doctor to verify
4. 📚 Read the Getting Started Guide
5. 🚀 Try your first project: claude chat

Common First Commands:

# Start interactive coding session
claude chat

# Generate code directly
claude "Create a Python FastAPI server with CORS"

# Debug existing code
claude "Why does this function return undefined?"

# Refactor code
claude "Refactor this to use async/await"