Chapter 2: 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 Chapter 3)

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

2.2 安装方法

bash

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

# Verify installation
claude --version

Method 2: Install via Homebrew (macOS/Linux)

Benefits: System-level package management, easy maintenance

bash

# macOS
brew install claude-code

# Verify installation
claude --version

Method 3: Download Standalone Executable

Benefits: No Node.js required, ready to use

Linux:

bash

# Download latest version
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64 -o claude

# Add execute permission
chmod +x claude

# Move to system path
sudo mv claude /usr/local/bin/

# Verify installation
claude --version

macOS:

bash

# Intel chip
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-macos-x64 -o claude

# Apple Silicon (M1/M2)
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-macos-arm64 -o claude

# Add execute permission
chmod +x claude

# Move to system path
sudo mv claude /usr/local/bin/

# Verify installation
claude --version

Windows (WSL2):

bash

# Execute in WSL2 terminal
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64 -o claude
chmod +x claude
sudo mv claude /usr/local/bin/
claude --version

Method 4: Install from Source (Developers)

Benefits: Latest features, customizable

bash

# Clone repository
git clone https://github.com/anthropics/claude-code.git
cd claude-code

# Install dependencies
npm install

# Build
npm run build

# Link globally
npm link

# Verify installation
claude --version

First Run

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

Step 1: Run Initialization Command

2.3 初次运行

bash

claude

On first run, Claude Code will:

Check if API Key is configured
Guide you through initial setup
Create configuration file

Step 2: Set API Key

You'll see a prompt like this:

2.4 配置文件位置

Welcome to Claude Code! 🎉

No API key found. Please enter your Anthropic API key:
(You can get one from https://console.anthropic.com/)

API Key: _

Enter your API Key and press Enter.

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

Step 3: Choose Default Model

Which model would you like to use by default?

› Claude Sonnet 4.5 (Recommended - balanced performance and cost)
  Claude Opus 4.5 (Most capable, higher cost)
  Claude Haiku (Fast and economical)

Recommended: Sonnet 4.5, which offers a good balance between performance and cost.

Step 4: Configuration Complete

2.5 基础配置选项

✓ Configuration saved to ~/.config/claude-code/config.json
✓ Setup complete!

You can now start using Claude Code:
  claude "your task here"

Or enter interactive mode:
  claude

For help, type: claude --help

Configuration File Locations

Claude Code configuration files are stored at:

Linux/macOS

2.6 常见问题排查

~/.config/claude-code/
├── config.json          # Main configuration
├── mcp-servers.json     # MCP server configuration
├── plugins.json         # Plugin configuration
└── .env                 # Environment variables (optional)

Windows (WSL)

/home/username/.config/claude-code/
├── config.json
├── mcp-servers.json
├── plugins.json
└── .env

View Configuration Path

bash

claude --config-path

Edit Configuration

bash

# Open with default editor
claude --edit-config

# Or edit manually
nano ~/.config/claude-code/config.json

Basic Configuration Options

Open config.json, you'll see something like:

json

{
  "api": {
    "key": "sk-ant-xxx",
    "baseUrl": "https://api.anthropic.com"
  },
  "model": {
    "default": "claude-sonnet-4-5",
    "temperature": 0.7,
    "maxTokens": 4096
  },
  "ui": {
    "colorScheme": "auto",
    "showLineNumbers": true,
    "syntaxHighlighting": true
  },
  "security": {
    "sandboxMode": true,
    "confirmCommands": true,
    "allowedDomains": []
  },
  "editor": {
    "default": "nano",
    "openFilesInEditor": false
  }
}

Main Configuration Options

Option	Description	Default
`api.key`	Anthropic API Key	None
`api.baseUrl`	API endpoint URL	https://api.anthropic.com
`model.default`	Default model to use	claude-sonnet-4-5
`model.temperature`	Generation temperature (0-1)	0.7
`model.maxTokens`	Maximum tokens	4096
`ui.colorScheme`	Color scheme (auto/light/dark)	auto
`ui.showLineNumbers`	Show line numbers	true
`security.sandboxMode`	Sandbox mode	true
`security.confirmCommands`	Confirm before command execution	true
`editor.default`	Default editor	nano

Troubleshooting

Issue 1: Command Not Found

Error Message:

2.7 验证安装

claude: command not found

Solution:

bash

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

2.8 更新 Claude Code

Error: Invalid API key

Solution:

Verify API Key format (should start with sk-ant-)
Check if Key has expired
Confirm account has sufficient balance
Re-enter API Key:

bash

claude --set-api-key

Issue 3: Network Connection Issues

Error Message:

Error: Failed to connect to API

Solution:

bash

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

2.9 卸载

Error: EACCES: permission denied

Solution:

bash

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

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

bash

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

bash

# 1. Check version
claude --version

# 2. View help
claude --help

# 3. Run simple test
claude "echo Hello from Claude Code"

# 4. Check configuration
claude --show-config

# 5. Test API connection
claude --test-connection

Expected Output:

bash

$ claude --version
Claude Code v1.5.0

$ claude --test-connection
✓ API connection successful
✓ Model: claude-sonnet-4-5 is available
✓ Configuration valid

Updating Claude Code

Keep Claude Code updated for latest features and fixes:

npm Update

bash

# Check current version
claude --version

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

# Verify update
claude --version

Homebrew Update

bash

brew upgrade claude-code

Standalone Executable Update

bash

# Download new version (replace old one)
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64 -o claude
chmod +x claude
sudo mv claude /usr/local/bin/

View Changelog

bash

claude --changelog

Uninstallation

To uninstall Claude Code:

npm Uninstall

bash

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

Homebrew Uninstall

bash

brew uninstall claude-code

Manual Uninstall

bash

# Remove executable
sudo rm /usr/local/bin/claude

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

# Remove cache (optional)
rm -rf ~/.cache/claude-code

Summary

In this chapter, we learned:

✅ Claude Code's system requirements and runtime environment
✅ Four installation methods: npm, Homebrew, standalone executable, source code
✅ 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: In Chapter 3, we'll learn in detail how to obtain and configure your Anthropic API Key.

Quick Reference

Installation Commands

bash

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

# Homebrew
brew install claude-code

# Standalone Executable (Linux)
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64 -o claude
chmod +x claude && sudo mv claude /usr/local/bin/

Common Commands

bash

claude --version          # Check version
claude --help             # Help information
claude --edit-config      # Edit configuration
claude --test-connection  # Test connection

Chapter 2: Installation and Setup ​

System Requirements ​

Operating System ​

Runtime Environment (Choose One) ​

Other Requirements ​

Installation Methods ​

Method 1: Install via npm (Recommended) ​

2.2 安装方法 ​

Method 2: Install via Homebrew (macOS/Linux) ​

Method 3: Download Standalone Executable ​

Method 4: Install from Source (Developers) ​

First Run ​

Step 1: Run Initialization Command ​

2.3 初次运行 ​

Step 2: Set API Key ​

2.4 配置文件位置 ​

Step 3: Choose Default Model ​

Step 4: Configuration Complete ​

2.5 基础配置选项 ​

Configuration File Locations ​

Linux/macOS ​

2.6 常见问题排查 ​

Windows (WSL) ​

View Configuration Path ​

Edit Configuration ​

Basic Configuration Options ​

Main Configuration Options ​

Troubleshooting ​

Issue 1: Command Not Found ​

2.7 验证安装 ​

Issue 2: Invalid API Key ​

2.8 更新 Claude Code ​

Issue 3: Network Connection Issues ​

Issue 4: Permission Issues ​

2.9 卸载 ​

Issue 5: Node.js Version Too Low ​

Verify Installation ​

Updating Claude Code ​

npm Update ​

Homebrew Update ​

Standalone Executable Update ​

View Changelog ​

Uninstallation ​

npm Uninstall ​

Homebrew Uninstall ​

Manual Uninstall ​

Summary ​

Quick Reference ​

Installation Commands ​

Common Commands ​

Chapter 2: Installation and Setup

System Requirements

Operating System

Runtime Environment (Choose One)

Other Requirements

Installation Methods

Method 1: Install via npm (Recommended)

2.2 安装方法

Method 2: Install via Homebrew (macOS/Linux)

Method 3: Download Standalone Executable

Method 4: Install from Source (Developers)

First Run

Step 1: Run Initialization Command

2.3 初次运行

Step 2: Set API Key

2.4 配置文件位置

Step 3: Choose Default Model

Step 4: Configuration Complete

2.5 基础配置选项

Configuration File Locations

Linux/macOS

2.6 常见问题排查

Windows (WSL)

View Configuration Path

Edit Configuration

Basic Configuration Options

Main Configuration Options

Troubleshooting

Issue 1: Command Not Found

2.7 验证安装

Issue 2: Invalid API Key

2.8 更新 Claude Code

Issue 3: Network Connection Issues

Issue 4: Permission Issues

2.9 卸载

Issue 5: Node.js Version Too Low

Verify Installation

Updating Claude Code

npm Update

Homebrew Update

Standalone Executable Update

View Changelog

Uninstallation

npm Uninstall

Homebrew Uninstall

Manual Uninstall

Summary

Quick Reference

Installation Commands

Common Commands