Installation

Requirements

Requirement	Version
Node.js	18 or later
npm	Bundled with Node.js 18+
Operating system	macOS, Linux, or Windows (WSL2 recommended)

Check your Node.js version:

node --version

Claude Code is distributed as an npm package and requires Node.js 18+. If you are on an older version, upgrade via your system package manager or a version manager (see below).

Install Claude Code

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

Verify the installation:

claude --version

You should see output like 1.x.x (Claude Code).

Do not use sudo npm install -g on macOS or Linux. If you get a permissions error, fix your npm prefix instead (see the npm docs).

Platform-specific setup

macOS
Linux
Windows

Install Node.js on macOS

Option 1 — Homebrew (recommended)

brew install node

Option 2 — nvm (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Open a new terminal, then:
nvm install --lts
nvm use --lts

Option 3 — Official installerDownload the macOS installer from nodejs.org.

Install Claude Code

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

macOS keychain integration

On macOS, Claude Code stores OAuth tokens in the macOS Keychain via security CLI. This is automatic — no extra setup is required. If you see a keychain access prompt the first time you log in, click Allow.

Install Node.js on Linux

Option 1 — nvm (recommended)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Open a new terminal, then:
nvm install --lts
nvm use --lts

Option 2 — NodeSource apt repository

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

Option 3 — System package manager

# Debian / Ubuntu
sudo apt-get install nodejs npm

# Fedora / RHEL
sudo dnf install nodejs npm

# Arch Linux
sudo pacman -S nodejs npm

Package manager versions of Node.js are often outdated. Use nvm or NodeSource to ensure you get Node.js 18+.

Install Claude Code

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

Credential storage on Linux

Claude Code uses libsecret (GNOME Keyring / KWallet) for secure credential storage on Linux. Install the required package for your distro:

# Debian / Ubuntu
sudo apt-get install libsecret-1-dev

# Fedora / RHEL
sudo dnf install libsecret-devel

# Arch Linux
sudo pacman -S libsecret

If no keyring is available (headless servers), Claude Code falls back to storing tokens in ~/.claude/.

Claude Code runs on Windows via WSL2 (Windows Subsystem for Linux). Running natively in the Windows Command Prompt or PowerShell is not supported.

Set up WSL2

Enable WSL2

Open PowerShell as Administrator and run:

wsl --install

Restart your machine when prompted.

Open a WSL2 terminal

Launch the Ubuntu app from the Start menu or open Windows Terminal and select the Ubuntu profile.

Install Node.js inside WSL2

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Open a new WSL2 terminal, then:
nvm install --lts
nvm use --lts

Install Claude Code

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

Windows Terminal with WSL2 gives the best experience. Install it from the Microsoft Store if you don’t have it.

Authentication setup

Claude Code supports multiple authentication methods. Choose the one that matches your access type.

Claude.ai OAuth (Pro / Team)

If you have a Claude.ai Pro or Team subscription, you can authenticate with your account directly.

Run claude

claude

Select Claude.ai login

When prompted, choose Claude.ai (not API key). Claude Code will open a browser window.

Complete the OAuth flow

Your OAuth tokens are stored in the system keychain and refreshed automatically. You will not need to re-authenticate unless you explicitly log out. To log out:

claude logout

Anthropic API key

If you access the API directly through console.anthropic.com, use an API key:

export ANTHROPIC_API_KEY=sk-ant-...
claude

To persist the key across sessions, add the export line to your shell profile:

export ANTHROPIC_API_KEY=sk-ant-...

Then reload your shell:

source ~/.zshrc   # or source ~/.bashrc

Do not commit your API key to version control. Use a secrets manager or a .env file excluded from git.

Amazon Bedrock

Access Claude through AWS Bedrock using your existing AWS credentials:

export CLAUDE_CODE_USE_BEDROCK=1
claude

Claude Code uses the AWS SDK’s standard credential chain — environment variables, ~/.aws/credentials, IAM roles, and so on. Make sure the IAM identity you are using has permission to invoke the Claude model on Bedrock. Additional environment variables for Bedrock:

Variable	Purpose
`AWS_PROFILE`	Named AWS profile to use
`AWS_REGION`	AWS region for Bedrock requests
`CLAUDE_CODE_SKIP_BEDROCK_AUTH`	Skip credential prefetch (useful in some IAM role setups)

Google Vertex AI

Access Claude through GCP Vertex AI:

export CLAUDE_CODE_USE_VERTEX=1
claude

Claude Code authenticates using Application Default Credentials (ADC). Set up ADC with:

gcloud auth application-default login

Additional environment variables:

Variable	Purpose
`GOOGLE_CLOUD_PROJECT`	GCP project ID
`CLAUDE_VERTEX_REGION`	Vertex AI region
`CLAUDE_CODE_SKIP_VERTEX_AUTH`	Skip credential prefetch

Enterprise and proxy configuration

Custom API base URL

To route Claude Code through an API gateway or proxy, set:

export ANTHROPIC_BASE_URL=https://your-proxy.example.com

Custom CA certificates

If your network uses a corporate CA:

export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt

Or enable system CA roots:

NODE_OPTIONS="--use-system-ca" claude

Managed settings

Enterprise administrators can distribute a policy settings file to all users. Set the path via:

export CLAUDE_CODE_SETTINGS_FILE=/etc/claude-code/policy.json

See Configuration for the full settings schema.

Verify your installation

Run the built-in diagnostics command to check for common problems:

claude doctor

This checks Node.js version, authentication state, keychain access, network connectivity, and MCP server configuration. Any issues are printed with suggested fixes.

Update Claude Code

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

Claude Code also checks for updates automatically at startup and prompts you when a new version is available. To disable auto-updates:

export CLAUDE_CODE_DISABLE_AUTO_UPDATER=1

Or from within a session:

> /upgrade

Uninstall

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

Configuration and session data are stored separately in ~/.claude/. Remove that directory if you want to delete all local state:

rm -rf ~/.claude

Next steps

Quickstart

Walk through your first Claude Code session.

Introduction

Understand how Claude Code works under the hood.

Configuration

Customize behavior with settings files and environment variables.

CLI flags

Full reference for every command-line flag.

Get Started

Core Concepts

Configuration

MCP Integration

Advanced

Requirements

Install Claude Code

Platform-specific setup

Install Node.js on macOS

Install Claude Code

macOS keychain integration

Install Node.js on Linux

Install Claude Code

Credential storage on Linux

Set up WSL2

Authentication setup

Claude.ai OAuth (Pro / Team)

Anthropic API key

Amazon Bedrock

Google Vertex AI

Enterprise and proxy configuration

Custom API base URL

Custom CA certificates

Managed settings

Verify your installation

Update Claude Code

Uninstall

Next steps

Quickstart

Introduction

Configuration

CLI flags

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

MCP Integration

Advanced

​Requirements

​Install Claude Code

​Platform-specific setup

​Install Node.js on macOS

​Install Claude Code

​macOS keychain integration

​Install Node.js on Linux

​Install Claude Code

​Credential storage on Linux

​Set up WSL2

​Authentication setup

​Claude.ai OAuth (Pro / Team)

​Anthropic API key

​Amazon Bedrock

​Google Vertex AI

​Enterprise and proxy configuration

​Custom API base URL

​Custom CA certificates

​Managed settings

​Verify your installation

​Update Claude Code

​Uninstall

​Next steps

Quickstart

Introduction

Configuration

CLI flags

Build docs developers (and LLMs) love

Requirements

Install Claude Code

Platform-specific setup

Install Node.js on macOS

Install Claude Code

macOS keychain integration

Install Node.js on Linux

Install Claude Code

Credential storage on Linux

Set up WSL2

Authentication setup

Claude.ai OAuth (Pro / Team)

Anthropic API key

Amazon Bedrock

Google Vertex AI

Enterprise and proxy configuration

Custom API base URL

Custom CA certificates

Managed settings

Verify your installation

Update Claude Code

Uninstall

Next steps