How to Install Claude Code 2025: Complete Setup Guide for Windows, Mac & Linux (Fix All Errors)

Introduction: Your AI Pair Programmer Awaits

Claude Code has revolutionized how developers write, debug, and refactor code. This official command-line interface from Anthropic brings the power of Claude 3.5 Sonnet directly to your terminal, transforming your coding workflow with AI-powered assistance that actually understands context and generates production-ready code.

Whether you're building a React application, debugging Python scripts, or refactoring legacy code, Claude Code acts as your intelligent pair programmer – available 24/7, never tired, and constantly learning from the latest programming patterns. The best part? Installation takes just 5-15 minutes, depending on your operating system.

However, the installation process isn't always straightforward. Windows users often encounter WSL-related errors, Mac users might face Node.js version conflicts, and everyone needs to navigate the API key setup. This comprehensive guide addresses every possible scenario, ensuring you'll have Claude Code running smoothly regardless of your setup.

We'll also reveal how to reduce your API costs by up to 50% without sacrificing functionality – a crucial consideration as you integrate AI assistance into your daily development workflow.

Prerequisites and System Requirements

Before installing Claude Code, ensure your system meets these requirements to avoid common installation failures:

Operating System Compatibility

Claude Code officially supports:

• macOS: 10.15 (Catalina) or later
• Linux: Ubuntu 18.04+, Debian 10+, Fedora 32+, CentOS 8+
• Windows: Windows 10 version 1903+ with WSL2 (Native Windows has limited support)

Required Software

Node.js 18.0.0 or higher is mandatory. Claude Code uses modern JavaScript features that require Node.js 18+. To check your current version:

node --version

If you see anything below v18.0.0, you'll need to update before proceeding.

Package Manager

You'll need either:

• npm (comes with Node.js)
• yarn (optional alternative)
• pnpm (optional alternative)

API Key Requirements

Claude Code requires an Anthropic API key. You have two options:

1. Official Anthropic API: Direct from Anthropic at standard rates
2. LaoZhang AI Gateway: Same API, 30-50% cheaper, with free $1 credit

We'll cover both options in the API setup section, but it's worth noting that many developers switch to LaoZhang AI after seeing their first monthly bill.

Hardware Requirements

• RAM: Minimum 4GB, recommended 8GB+
• Storage: 500MB free space
• Internet: Stable connection for API calls

Quick Installation Guide (For Experienced Developers)

If you're comfortable with command-line tools and have Node.js 18+ installed, here's the fastest path:

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

# Set your API key (replace with your actual key)
export ANTHROPIC_API_KEY="sk-ant-..."

# Test the installation
claude-code --version

# Your first command
claude-code "Write a function to validate email addresses"

That's it! Claude Code is now ready to use. However, if you encountered any errors or want more detailed instructions, continue reading for platform-specific guides.

Quick Troubleshooting

If the quick install failed, check these common issues:

# Permission denied? Use sudo (macOS/Linux)
sudo npm install -g @anthropic-ai/claude-code

# Command not found? Add npm global bin to PATH
export PATH="$PATH:$(npm config get prefix)/bin"

# API key not working? Verify it's set correctly
echo $ANTHROPIC_API_KEY

Detailed Installation by Operating System

macOS Installation Guide

macOS users typically have the smoothest installation experience. Here's the complete process:

Step 1: Install or Update Node.js

If you have Homebrew installed (recommended):

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node

# Verify installation
node --version  # Should show v18.0.0 or higher
npm --version   # Should show 8.0.0 or higher

Without Homebrew, download Node.js from nodejs.org.

Step 2: Install Claude Code

# Install globally for system-wide access
npm install -g @anthropic-ai/claude-code

# Verify installation
claude-code --version

Step 3: Configure Shell (zsh)

Modern macOS uses zsh by default. Add these lines to your ~/.zshrc:

# Open zsh config
nano ~/.zshrc

# Add these lines
export ANTHROPIC_API_KEY="your-api-key-here"
alias cc="claude-code"  # Optional: shorter command

# Save and reload
source ~/.zshrc

Step 4: First Test

# Test with a simple command
claude-code "Create a Python function to calculate fibonacci numbers"

# You should see Claude generating code in your terminal

Linux Installation Guide

Linux installation varies slightly by distribution, but the process is generally straightforward:

Step 1: Update System and Install Node.js

For Ubuntu/Debian:

# Update package list
sudo apt update

# Install Node.js via NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# Verify installation
node --version
npm --version

For Fedora/RHEL/CentOS:

# Install Node.js
sudo dnf install nodejs

# Or use NodeSource for latest version
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install nodejs

Step 2: Install Claude Code

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

# Fix npm permissions if needed
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Step 3: Configure Environment

# Add to ~/.bashrc or ~/.bash_profile
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
echo 'alias cc="claude-code"' >> ~/.bashrc
source ~/.bashrc

Step 4: Verify Installation

# Check installation
which claude-code
claude-code --help

Windows Installation Guide (The Right Way)

Windows users face the most challenges with Claude Code, but using WSL2 solves virtually all compatibility issues:

Option 1: WSL2 Installation (Recommended)

Step 1: Enable WSL2

Open PowerShell as Administrator and run:

# Enable WSL
wsl --install

# Set WSL2 as default
wsl --set-default-version 2

# Install Ubuntu from Microsoft Store
# Or via command line:
wsl --install -d Ubuntu

Step 2: Set Up Ubuntu Environment

Once Ubuntu is installed, open it from the Start menu:

# Update packages
sudo apt update && sudo apt upgrade -y

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# Install build tools (important for some npm packages)
sudo apt install -y build-essential

Step 3: Install Claude Code in WSL

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

# Configure API key
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Step 4: Windows Terminal Integration

For the best experience, use Windows Terminal:

1. Install Windows Terminal from Microsoft Store
2. Set Ubuntu as default profile
3. Configure settings for better visibility

Option 2: Native Windows (Limited Support)

If you must use native Windows:

# Install Node.js from nodejs.org first

# Then in PowerShell:
npm install -g @anthropic-ai/claude-code

# Set environment variable
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-key-here", "User")

⚠️ Warning: Native Windows installation often fails due to build tool requirements and path length limitations. WSL2 is strongly recommended.

API Key Setup and Cost Optimization

Getting Your API Key

You have two options for API access:

Option 1: Official Anthropic API

1. Visit console.anthropic.com
2. Create an account and add payment method
3. Generate an API key
4. Expect to pay $3/$15 per million tokens (input/output)

Option 2: LaoZhang AI (30-50% Cheaper)

For developers looking to reduce costs without changing their code:

1. Visit laozhang.ai
2. Sign up and get free $1 credit instantly
3. Generate your API key
4. Pay only $1.50-$2.10 per million input tokens
5. Same API endpoints, just change the key

Setting Up Your API Key

Environment Variable (Recommended)

# Linux/macOS (add to ~/.bashrc or ~/.zshrc)
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY="sk-ant-..."

# Windows (Command Prompt)
set ANTHROPIC_API_KEY=sk-ant-...

Per-Command Usage

# Pass key directly (not recommended for security)
claude-code --api-key "sk-ant-..." "Your prompt here"

Configuration File

Create ~/.claude-code/config.json:

{
  "apiKey": "sk-ant-...",
  "model": "claude-3-5-sonnet-20241022",
  "maxTokens": 4096,
  "temperature": 0.3
}

Cost Monitoring and Optimization

Track your usage to avoid surprises:

# Check your usage (with official API)
claude-code usage

# Estimate costs for a project
claude-code estimate ./src

Cost-Saving Tips:

1. Use Caching: Cache common prompts and contexts
2. Batch Requests: Group related tasks together
3. Choose the Right Model: Use Haiku for simple tasks
4. Set Token Limits: Prevent runaway costs

# Set maximum tokens per request
claude-code --max-tokens 1000 "Your prompt"

For production use, consider implementing these strategies:

// Example: Cost-optimized configuration
const config = {
  model: "claude-3-5-haiku", // Cheaper for simple tasks
  maxTokens: 2000,          // Limit response length
  temperature: 0.2,         // More deterministic = fewer retries
  cache: true,              // Enable prompt caching
};

IDE Integration

Claude Code works seamlessly with popular development environments:

VS Code Integration

Install the Claude Code extension:

# Via command line
code --install-extension anthropic.claude-code

# Or search "Claude Code" in VS Code extensions

Configure in VS Code settings:

{
  "claude-code.apiKey": "${env:ANTHROPIC_API_KEY}",
  "claude-code.model": "claude-3-5-sonnet-20241022",
  "claude-code.shortcuts": {
    "explain": "Ctrl+Shift+E",
    "refactor": "Ctrl+Shift+R",
    "test": "Ctrl+Shift+T"
  }
}

Vim/Neovim Setup

Add to your .vimrc or init.vim:

" Claude Code integration
function! ClaudeCode(prompt)
  let result = system('claude-code "' . a:prompt . '"')
  put =result
endfunction

" Keybindings
nnoremap <leader>cc :call ClaudeCode(input('Claude: '))<CR>
vnoremap <leader>ce :'<,'>!claude-code explain<CR>
vnoremap <leader>cr :'<,'>!claude-code refactor<CR>

JetBrains IDEs

For IntelliJ IDEA, PyCharm, WebStorm, etc.:

1. Install "Claude Code" plugin from marketplace
2. Configure API key in Settings → Tools → Claude Code
3. Use Alt+C to invoke Claude Code

Terminal Workflow Enhancement

Create useful aliases in your shell config:

# Quick commands
alias cc="claude-code"
alias cce="claude-code explain"
alias ccr="claude-code refactor"
alias cct="claude-code test"
alias ccd="claude-code debug"

# Project-specific helpers
alias ccpr="claude-code 'Review this PR and suggest improvements'"
alias cccommit="claude-code 'Write a commit message for these changes'"

Troubleshooting Common Issues

"command not found" Error

This is the most common issue after installation:

# Check if npm global bin is in PATH
echo $PATH
npm config get prefix

# Add to PATH (Linux/macOS)
export PATH="$PATH:$(npm config get prefix)/bin"

# Make permanent
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc

Permission Denied Errors

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Or reinstall with sudo (less recommended)
sudo npm install -g @anthropic-ai/claude-code

WSL-Specific Problems

WSL Clock Sync Issues

# Fix time sync problems
sudo hwclock -s
sudo ntpdate time.windows.com

WSL Network Issues

# Reset WSL network
wsl --shutdown
# Then restart WSL

API Key Errors

# Verify API key is set
echo $ANTHROPIC_API_KEY

# Test API key
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-3-5-sonnet-20241022", "max_tokens": 10, "messages": [{"role": "user", "content": "Hi"}]}'

Node.js Version Conflicts

# Use nvm to manage Node versions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install and use Node 18
nvm install 18
nvm use 18
nvm alias default 18

Proxy/Firewall Issues

For corporate environments:

# Set proxy for npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Set for Claude Code
export HTTPS_PROXY=http://proxy.company.com:8080

Advanced Configuration

Custom Model Selection

# Use different models for different tasks
claude-code --model claude-3-5-haiku "Quick formatting fix"
claude-code --model claude-3-5-sonnet "Complex algorithm implementation"

Shell Completions

Enable tab completion for better productivity:

# Bash
claude-code completions bash > ~/.claude-code-completion.bash
echo "source ~/.claude-code-completion.bash" >> ~/.bashrc

# Zsh
claude-code completions zsh > ~/.claude-code-completion.zsh
echo "source ~/.claude-code-completion.zsh" >> ~/.zshrc

Context Window Optimization

# Configure context window size
claude-code config set contextSize 100000

# Use context from files
claude-code --context ./src/utils.js "Add error handling to all functions"

Cost-Saving Configurations

# Set up aliases for different cost profiles
alias cc-cheap="claude-code --model claude-3-5-haiku --max-tokens 1000"
alias cc-quality="claude-code --model claude-3-5-sonnet --max-tokens 4000"
alias cc-fast="claude-code --model claude-3-5-haiku --temperature 0"

Batch Processing

Create a batch file for multiple operations:

#!/bin/bash
# batch-refactor.sh

files=$(find ./src -name "*.js")
for file in $files; do
  echo "Refactoring $file..."
  claude-code refactor "$file" --output "$file.refactored"
done

First Steps After Installation

Now that Claude Code is installed, here's how to get started effectively:

Testing Your Installation

Run these commands to ensure everything works:

# Version check
claude-code --version

# Help documentation
claude-code --help

# Simple test
claude-code "Write a hello world in Python"

Essential First Commands

# Explain code
claude-code explain ./complex-function.js

# Generate documentation
claude-code document ./src/api/

# Create unit tests
claude-code test ./utils/validation.js

# Debug errors
claude-code debug "TypeError: Cannot read property 'x' of undefined"

Your First AI-Assisted Coding Session

Try this practical example:

# Create a new project
mkdir my-ai-project && cd my-ai-project

# Generate a complete Express.js API
claude-code "Create a RESTful API for a todo app with Express.js, including CRUD operations, validation, and error handling"

# Generate tests
claude-code test ./server.js

# Add authentication
claude-code "Add JWT authentication to the existing Express API"

Best Practices for Effective Use

1. Be Specific: Detailed prompts yield better results

   # Good
   claude-code "Create a React hook for infinite scrolling with debouncing and error handling"
   
   # Less effective
   claude-code "Make scroll hook"
   

2. Provide Context: Include relevant files

   claude-code --context ./types.ts "Implement the UserService interface"
   

3. Iterate Incrementally: Build complex features step by step

   claude-code "1. Create the data model"
   claude-code "2. Add validation"
   claude-code "3. Implement business logic"
   

4. Review Generated Code: Always review and test AI-generated code

   # Generate with tests
   claude-code "Create function with comprehensive tests"
   

Conclusion

Claude Code transforms how developers work, bringing AI assistance directly to your terminal. With this guide, you've successfully installed Claude Code on your system, configured it for optimal performance, and learned how to troubleshoot common issues.

Remember these key takeaways:

• Platform Matters: Use WSL2 on Windows for the best experience
• API Costs Add Up: Consider LaoZhang AI for 30-50% savings on the same API
• Integration is Key: Set up IDE integration for seamless workflow
• Start Small: Begin with simple tasks and gradually increase complexity

Claude Code is more than just a tool – it's your AI pair programmer, ready to help you write better code faster. Whether you're debugging at 3 AM or architecting a new system, Claude Code is there to assist.

For ongoing support and updates:

• Join the Claude Code community on Discord
• Check the official documentation
• Report issues on the GitHub repository

Start coding with AI assistance today, and experience the future of software development. Remember, the best way to learn is by doing – so open your terminal and start exploring what Claude Code can do for your projects.

Happy coding with your new AI assistant!