Installation & Authentication

This guide covers everything you need to install Claude Code and authenticate for immediate use. Whether you’re on macOS, Windows, or Linux, we’ll get you coding with AI assistance in under 15 minutes.

System Requirements

Prerequisites

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

• Operating System:
  • macOS 10.15+
  • Ubuntu 20.04+/Debian 10+
  • Windows 10+ (with WSL 1/2 or Git for Windows)
• Hardware: 4GB+ RAM minimum
• Software: Node.js 18+ installed
• Network: Internet connection required
• Shell: Works best with Bash, Zsh, or Fish
• Location: Must be in an Anthropic supported country

Installation Methods

Standard Installation (Recommended)

1. Install via npm

   Open your terminal and run:

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

   Caution

   Do NOT use sudo npm install -g as this can lead to permission issues and security risks.

2. Verify installation

   Check that Claude Code is properly installed:

   claude --version

3. Run health check

   Ensure everything is configured correctly:

   claude doctor

Alternative Installation Methods

Local Installation

If you encounter permission errors, migrate to a local installation:

# After initial global install attempt
claude migrate-installer

This moves Claude Code to ~/.claude/local/ and sets up a shell alias. No sudo required for future updates.

Native Binary (Alpha)

For a platform-native installation:

# From existing installation
claude install

# Or fresh install via curl
curl -fsSL claude.ai/install.sh | bash

Platform support: macOS, Linux, Windows (via WSL)

Windows Setup

WSL (Recommended)

Using Windows Subsystem for Linux

Both WSL 1 and WSL 2 are supported. Install Node.js within your WSL environment:

# Inside WSL
sudo apt update
sudo apt install nodejs npm
npm install -g @anthropic-ai/claude-code

Tip

If you see OS detection errors, ensure WSL is using Linux npm:

npm config set os linux
which npm  # Should show /usr/bin/npm, not /mnt/c/...

Native Windows

Using Git Bash

1. Install Git for Windows
2. For portable Git installations, set the bash path:

   $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

3. Install Claude Code via npm in Git Bash

Authentication Options

Claude Code offers three authentication methods to suit different needs:

Anthropic Console (Default) Connect through the Anthropic Console with OAuth. Requires active billing at console.anthropic.com

Claude Pro/Max Plan Unified subscription for both Claude Code and web interface. Same price, more value

Enterprise Platforms Use Amazon Bedrock or Google Vertex AI for enterprise deployments

Quick Authentication

1. Start Claude Code

   cd your-project
   claude

2. Choose authentication method

   On first run, you’ll see options like:

   Welcome to Claude Code!
   
   Choose your authentication method:
   1. Anthropic Console (default)
   2. Claude Pro/Max subscription
   3. Enterprise (Bedrock/Vertex)

3. Complete authentication

   • Console/Claude.ai: Browser opens for OAuth flow
   • Enterprise: Configure environment variables first (see below)

Enterprise Authentication

Amazon Bedrock

1. Enable model access in AWS

   • Navigate to Amazon Bedrock console
   • Request access to Claude models
   • Wait for approval (usually instant)

2. Configure credentials

   AWS CLI

   aws configure
   export CLAUDE_CODE_USE_BEDROCK=1
   export AWS_REGION=us-east-1

   Environment Variables

   export AWS_ACCESS_KEY_ID=your-key-id
   export AWS_SECRET_ACCESS_KEY=your-secret-key
   export AWS_SESSION_TOKEN=your-session-token  # If using temporary credentials
   export CLAUDE_CODE_USE_BEDROCK=1
   export AWS_REGION=us-east-1

   Bedrock API Key

   export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key
   export CLAUDE_CODE_USE_BEDROCK=1
   export AWS_REGION=us-east-1

3. Start Claude Code

   claude

Google Vertex AI

1. Enable APIs in Google Cloud

   • IAM Credentials API
   • Security Token Service API
   • Vertex AI API

2. Request model access

   • Go to Vertex AI Model Garden
   • Search for “Claude” models
   • Request access (24-48 hour approval)

3. Configure authentication

   # Authenticate with Google Cloud
   gcloud auth application-default login
   
   # Set environment variables
   export CLAUDE_CODE_USE_VERTEX=1
   export CLOUD_ML_REGION=us-east5
   export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

4. Start Claude Code

   claude

Behind Corporate Proxy

If you’re behind a corporate proxy:

# HTTP/HTTPS proxy
export HTTPS_PROXY='https://proxy.company.com:8080'
export HTTP_PROXY='http://proxy.company.com:8080'

# If using self-signed certificates
export NODE_TLS_REJECT_UNAUTHORIZED=0  # Use with caution

For permanent proxy configuration, add to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Troubleshooting Common Issues

Permission Errors on Linux/macOS

Quick Fix

# Migrate to local installation
claude migrate-installer

# Restart your shell
source ~/.bashrc  # or ~/.zshrc

NPM Prefix Fix

# Create user-writable npm directory
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

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

Windows WSL Issues

Node not found error: Ensure you’re using Linux Node.js, not Windows:

which node  # Should show /usr/bin/node, not /mnt/c/...

OS detection issues: Force Linux mode:

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check

Authentication Issues

If authentication fails:

# Clear stored credentials
rm -rf ~/.config/claude-code/auth.json

# Try again
claude

Auto-Update Failures

Disable auto-updates if needed:

# Via configuration
claude config set autoUpdates false --global

# Or environment variable
export DISABLE_AUTOUPDATER=1

Verify Your Installation

Once installed and authenticated, verify everything works:

1. Check version and diagnostics

   claude doctor

2. Test basic functionality

   claude "Create a hello world Python script"

3. Check authentication status

   claude /whoami

Pro Tip

For the best experience, many developers run Claude Code with:

claude --dangerously-skip-permissions

This skips constant permission prompts (similar to Cursor’s old “yolo mode”). Use at your discretion based on your security requirements.

Next Steps

Configure Your Environment Set up IDE integration, keyboard shortcuts, and project-specific settings

Initialize Your First Project Create a CLAUDE.md file and configure project context

Quick Reference

Command	Purpose
claude --version	Check installed version
claude doctor	Run diagnostics
claude update	Manually update Claude Code
claude migrate-installer	Fix permission issues
claude config set <key> <value>	Configure settings
claude /logout	Sign out and clear credentials

Remember: Claude Code auto-updates by default, keeping you on the latest version with newest features and security fixes.