#Installation and Setup

#System Requirements

Before installing Claude Code, ensure your system meets these requirements:

#Operating System

• ✅ Linux (Recommended)
• ✅ macOS (Recommended)
• ✅ Windows (via WSL2)

#Runtime Environment (Choose One)

Option 1: Node.js Environment

• Node.js 18.0.0 or higher
• npm or yarn package manager

Option 2: Standalone Executable

• No Node.js required
• Download platform-specific binary directly

#Other Requirements

• At least 2GB available memory
• Stable internet connection (for API calls)
• Command-line terminal (Terminal/iTerm2/Windows Terminal, etc.)
• Anthropic API Key (detailed in API Configuration)

#Installation Methods

Claude Code offers multiple installation methods—choose the one that suits you best:

#Method 1: Install via npm (Recommended)

Benefits: Easy updates, cross-platform, automatic dependency management

# Global installation
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

#Method 2: Native Install Script (No Node.js Required)

Benefits: No Node.js dependency, picks the right binary for your platform, self-updating

macOS / Linux / WSL:

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

# Verify installation
claude --version

Windows (PowerShell):

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

# Verify installation
claude --version

#Method 3: IDE Extensions and Desktop App

Beyond the CLI, Claude Code is also available as:

• VS Code extension: Search "Claude Code" in the VS Code marketplace and use it directly from the editor sidebar
• JetBrains plugin: Supports IntelliJ IDEA, PyCharm, WebStorm, and more
• Desktop app: macOS and Windows desktop clients, convenient for managing multiple parallel sessions

Note: There is no official brew install claude-code formula, and Claude Code cannot be built from source (the anthropics/claude-code repository is mainly for issue tracking and documentation). Use npm or the native install script above.

#First Run

After installation, let's perform first-run configuration:

#Step 1: Start in a Project Directory

cd your-project
claude

On first run, Claude Code will guide you through:

1. Choosing a UI theme (dark/light, etc.)
2. Logging in: either with a Claude subscription account (Pro/Max plan, browser OAuth) or an Anthropic Console account (pay-per-use API billing)
3. Trusting the current directory: confirm that Claude Code may read the project's files

#Step 2: Login Options

The two login methods differ as follows:

You can also skip the login flow and provide an API key via environment variable:

export ANTHROPIC_API_KEY=sk-ant-xxx
claude

Note: If you don't have an API Key yet, see the next chapter (API Configuration) for how to obtain one.

#Step 3: Start Using It

# Interactive mode
claude

# Run a one-off task (prints the result and exits)
claude -p "explain this project's structure"

# Inside a session, type /help to list available commands

#Configuration File Locations

Claude Code configuration files are stored at:

~/.claude/                    # User-level config directory
├── settings.json             # User settings (model, permissions, env, ...)
├── CLAUDE.md                 # Global memory/instructions file
├── commands/                 # Custom slash commands
└── agents/                   # Custom subagents

project directory/
├── .claude/settings.json        # Shared project settings (checked into git)
├── .claude/settings.local.json  # Personal project settings (not committed)
├── .mcp.json                    # Project MCP server configuration
└── CLAUDE.md                    # Project memory/instructions file

#Edit Configuration

# Inside a session, use /config to open the settings UI
claude
> /config

# Or edit manually
nano ~/.claude/settings.json

#Basic Configuration Options

Open ~/.claude/settings.json; common options look like this:

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(npm run test:*)"],
    "deny": ["Read(./.env)"]
  },
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

#Main Configuration Options

See the official settings documentation for the full list.

#Troubleshooting

#Issue 1: Command Not Found

Error Message:

claude: command not found

Solution:

# Check if properly installed
npm list -g @anthropic-ai/claude-code

# Check PATH environment variable
echo $PATH

# If using standalone executable, ensure correct location
which claude

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

#Issue 2: Invalid API Key

Error Message:

Error: Invalid API key

Solution:

1. Verify API Key format (should start with sk-ant-)
2. Check if Key has expired
3. Confirm account has sufficient balance
4. Log in again or update the key:

# Re-login inside a session
claude
> /login

# Or update the key in the environment variable
export ANTHROPIC_API_KEY=sk-ant-new-key

#Issue 3: Network Connection Issues

Error Message:

Error: Failed to connect to API

Solution:

# Check network connection
ping api.anthropic.com

# Check proxy settings (if using proxy)
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Set proxy (if needed)
export HTTPS_PROXY=http://proxy.example.com:8080

#Issue 4: Permission Issues

Error Message:

Error: EACCES: permission denied

Solution:

# Linux/macOS - Fix permissions
sudo chown -R $(whoami) ~/.claude

# Or use npx (no global installation needed)
npx @anthropic-ai/claude-code "your task"

#Issue 5: Node.js Version Too Low

Error Message:

Error: Claude Code requires Node.js 18 or higher

Solution:

# Check current version
node --version

# Update Node.js using nvm
nvm install 18
nvm use 18

# Or download standalone executable (no Node.js required)

#Verify Installation

After installation, run these commands to verify everything works:

# 1. Check version
claude --version

# 2. View help
claude --help

# 3. Run a simple one-off test
claude -p "say hello"

# 4. Check configuration
claude config list

# 5. Health check (diagnoses installation and connection issues)
claude doctor

Expected Output:

$ claude --version
2.x.x (Claude Code)

$ claude doctor
✓ Installation healthy
✓ Auth configured

#Updating Claude Code

Keep Claude Code updated for latest features and fixes:

#npm Update

# Check current version
claude --version

# Update to latest version
npm update -g @anthropic-ai/claude-code

# Verify update
claude --version

#Native Install Update

# The native installer is self-updating; you can also trigger an update manually
claude update

#View Changelog

See the official repository's CHANGELOG.

#Uninstallation

To uninstall Claude Code:

#npm Uninstall

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

#Native Install Uninstall

# Remove the executable and install directory
rm -rf ~/.local/bin/claude ~/.local/share/claude

# Remove configuration (optional)
rm -rf ~/.claude ~/.claude.json

#Summary

In this chapter, we learned:

• ✅ Claude Code's system requirements and runtime environment
• ✅ Installation methods: npm, native install script, IDE extensions, and desktop app
• ✅ First-run configuration process
• ✅ Configuration file locations and basic options
• ✅ Troubleshooting common issues
• ✅ Installation verification, updates, and uninstallation

You've now successfully installed Claude Code!

Next Step: Continue with API Configuration to obtain and configure your Anthropic API Key.

#Quick Reference

#Installation Commands

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

# Native install script (macOS/Linux/WSL)
curl -fsSL https://claude.ai/install.sh | bash

# Native install script (Windows PowerShell)
irm https://claude.ai/install.ps1 | iex

#Common Commands

claude --version          # Check version
claude --help             # Help information
claude config list        # Show configuration
claude doctor             # Health check / diagnose issues
claude update             # Update to the latest version