Claude Code: Claude Code Installation and Usage
Last updated: 2026-08-31
Installing Claude Code requires just one npm command, but your environment needs to be ready first. This chapter walks you through system requirements to installation and first run.
💡 Tip: Claude Code installs globally via npm, requiring Node.js 18+. After installation, launch with the
claude command.
📋 Prerequisites: Chapter 1 - Claude Code Introduction and How It Works
1. What You'll Learn
- System requirements and prerequisites
- npm global installation of Claude Code
- First run and authentication configuration
- Basic usage flow
- Common installation troubleshooting
2. System Requirements
(1) Hardware and Software Requirements
| Requirement | Minimum | Recommended |
|---|---|---|
| OS | macOS 12+ / Ubuntu 20.04+ / Windows 10+ | macOS 14+ / Ubuntu 22.04+ |
| Node.js | 18.x | 20.x+ |
| npm | 9.x | 10.x+ |
| Memory | 4 GB | 8 GB+ |
| Network | HTTPS outbound | Stable low latency |
(2) Check Existing Environment
BASH
# Check Node.js version
node --version
# Need v18+
# Check npm version
npm --version
# Need 9+
# If no Node.js, install with nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20
3. Installing Claude Code
(1) npm Global Install
BASH
# Global install Claude Code
npm install -g @anthropic-ai/claude-code
# Verify installation
claude --version
# Output similar to: claude-code/1.0.x
(2) Alternative Installation Methods
BASH
# Run directly with npx (no global install needed)
npx @anthropic-ai/claude-code
# Build from source
git clone https://github.com/anthropics/claude-code.git
cd claude-code
npm install
npm run build
npm link
▶ Example 1: Complete Installation Process
BASH
# Alice's complete installation process
node --version # v20.11.0 ✓
npm --version # 10.2.4 ✓
# Install Claude Code
npm install -g @anthropic-ai/claude-code
# Verify
claude --version # claude-code/1.0.12 ✓
# First run (will guide authentication)
claude
# → Opening browser for authentication...
# → Authentication successful!
4. First Run and Authentication
(1) Authentication Methods
Claude Code supports three authentication methods:
| Method | Use Case | Command |
|---|---|---|
| Anthropic Account | Personal users | claude (auto-guided) |
| API Key | Enterprise/Team | Set environment variable |
| OAuth | Enterprise SSO | claude auth |
(2) API Key Configuration
BASH
# Method 1: Environment variable (recommended)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
# Method 2: Write to shell config file
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"' >> ~/.bashrc
source ~/.bashrc
# Method 3: .env file
echo 'ANTHROPIC_API_KEY=sk-ant-api03-xxxxx' > .env
▶ Example 2: First Launch
BASH
$ claude
╭─────────────────────────────────────╮
│ Welcome to Claude Code! │
│ │
│ Let's get you set up. │
╰─────────────────────────────────────╯
? How would you like to authenticate?
❯ Anthropic Account (browser login)
API Key
OAuth (Enterprise)
# After selecting Anthropic Account:
# → Browser opens automatically
# → Login and authorize
# → "Authentication successful!"
5. Basic Usage Flow
(1) Launch in a Project
BASH
# Navigate to your project directory
cd ~/my-project
# Launch Claude Code
claude
# Or launch with a task directly
claude "Help me add a user registration feature"
(2) Interactive Mode
TEXT
📖 Display only
$ claude
╭─ Claude Code ─────────────────────────╮
│ Project: my-project │
│ Model: claude-sonnet-4-20250514 │
╰───────────────────────────────────────╯
> Show me the project structure
Claude: Let me read the project structure...
- src/
- index.ts
- routes/
- utils/
- package.json
- tsconfig.json
> Modify index.ts, add a health check endpoint
Claude: I'll add a health check endpoint...
→ Reading src/index.ts
→ Modifying src/index.ts
→ Running: npm run build ✓
6. Common Installation Troubleshooting
▶ Example 3: Troubleshooting Checklist
BASH
# Problem 1: npm install permission error
npm install -g @anthropic-ai/claude-code
# EACCES: permission denied
# Solution:
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
# Problem 2: Node.js version too low
node --version # v16.x
# Solution:
nvm install 20
nvm use 20
# Problem 3: Network timeout
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
# Problem 4: Windows path issues
# Ensure Node.js install path is in PATH
where node
where claude
| Problem | Cause | Solution |
|---|---|---|
command not found: claude |
PATH not configured | Check npm global install path |
EACCES |
Insufficient permissions | Use nvm or modify npm prefix |
ETIMEDOUT |
Network issues | Switch mirror source |
node_modules error |
Low Node version | Upgrade to Node 18+ |
| Authentication failure | Invalid API Key | Check Key format and quota |
7. Comprehensive Example: From Zero to Running
BASH
# Complete installation to first use flow
# 1. Confirm environment
node --version && npm --version
# 2. Install
npm install -g @anthropic-ai/claude-code
# 3. Authenticate
export ANTHROPIC_API_KEY="sk-ant-api03-your-key"
# 4. Create test project
mkdir hello-claude && cd hello-claude
git init
# 5. First run
claude "Create an Express.js Hello World project"
# Claude Code output:
# → Initializing project...
# → Creating package.json
# → Installing express
# → Creating index.js
# → Creating .gitignore
# → Running: node index.js
# → Server started on port 3000 ✓
❓ FAQ
Q Can I use Claude Code on Windows?
A Yes. Via WSL2 or native Node.js installation. WSL2 recommended for best compatibility.
Q Do I need a VPN for installation?
A npm package installation usually doesn't, but connecting to the Anthropic API does. The API endpoint is overseas; proxy needed if network is blocked.
Q Where do I get an API Key?
A Log in to console.anthropic.com, create one in the API Keys page. New accounts have free credits.
Q Can I install offline?
A Installation requires network, and running requires network (calling API). No fully offline solution yet.
Q How to uninstall?
A
npm uninstall -g @anthropic-ai/claude-code completely removes it.Q How to update?
A
npm update -g @anthropic-ai/claude-code updates to the latest version.📖 Summary
- Node.js 18+ is a prerequisite; recommend using nvm for version management
npm install -g @anthropic-ai/claude-codefor one-command install- Three authentication methods: Anthropic Account, API Key, OAuth
- Run
claudein your project directory to start - Common issues mostly related to permissions, versions, and network
📝 Exercises
- Basic (⭐): Install Claude Code on your machine and run
claude --version, screenshot to confirm success. - Intermediate (⭐⭐): Configure API Key environment variable, run
claudein an empty directory, have it create a simple project. - Advanced (⭐⭐⭐): Install Claude Code in WSL2, compare usage experience between native Windows and WSL2.
