Installation

System requirements, install instructions, authentication, and setup verification for Claude Code on macOS, Linux, and Windows.

Requirements

• Node.js 18 or later
• npm 8 or later (included with Node.js)
• Operating system: macOS, Linux, or Windows (via WSL2)

macOS

macOS 12 (Monterey) or later is recommended. The npm installation works on both Intel and Apple Silicon.

If you use Homebrew to manage Node.js, install it first:

brew install node

Then install Claude Code:

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

Linux

Most modern Linux distributions are supported. Use a version manager like nvm or mise to install Node.js without requiring sudo.

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

If ~/.local/bin is not in your PATH, Claude Code will warn you. Add it with:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows (WSL2)

Claude Code runs on Windows through WSL2 (Windows Subsystem for Linux). Native Windows without WSL is not supported.

1. Install WSL2: open PowerShell as Administrator and run:

wsl --install

2. Open your WSL terminal (Ubuntu is the default distribution).

3. Install Node.js inside WSL using nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

4. Install Claude Code:

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

Run all claude commands from inside your WSL terminal, not from PowerShell or Command Prompt.

Authenticate

Run the /login command to sign in with your Anthropic account:

claude /login

Claude Code opens a browser window and starts an OAuth 2.0 flow. You can authenticate with:

• Claude Pro or Max subscription — sign in via claude.ai
• Anthropic Console (API billing) — sign in via console.anthropic.com

After you authorize in the browser, your credentials are stored securely (macOS Keychain on macOS, or an encrypted local file on Linux and Windows/WSL). You only need to run /login once, or when you want to switch accounts.

API key alternative

If you prefer to authenticate with an API key directly instead of OAuth, set the ANTHROPIC_API_KEY environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Add this line to your shell profile (~/.zshrc, ~/.bashrc, etc.) to make it permanent. When this variable is set, Claude Code uses it instead of the stored OAuth token.

Verify your setup

Run the /doctor command to check that everything is configured correctly:

claude /doctor

/doctor shows:

• Your Claude Code version and installation type
• Whether auto-updates are enabled
• Your ripgrep status (used for fast codebase search)
• Any configuration warnings with suggested fixes

A healthy setup shows no warnings. If /doctor reports an issue, it also tells you how to fix it.

Troubleshooting

'claude' command not found after install

Your npm global bin directory may not be in your PATH. Find it with:

npm config get prefix

Then add <prefix>/bin to your PATH. For example:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission denied when installing globally

Avoid using sudo npm install -g. Instead, configure npm to use a directory you own:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

Or use a Node.js version manager like nvm, which avoids the permission issue entirely.

Login fails or browser does not open

If the browser does not open automatically, Claude Code displays the login URL in the terminal. Copy and paste it into your browser manually.

If the OAuth flow fails with an SSL error, check whether a corporate proxy or VPN is intercepting HTTPS traffic. You may need to configure your proxy settings or use an API key instead.

Multiple Claude Code installations detected

If you have both an npm global install and a native install, /doctor will warn you. Remove the one you are not using:

# Remove the npm global install
npm -g uninstall @anthropic-ai/claude-code

Then re-run claude /doctor to confirm the warning is resolved.

ripgrep not working

Claude Code uses ripgrep for fast file search. If /doctor reports a ripgrep problem, install it with your system package manager:

# macOS
brew install ripgrep

# Ubuntu / Debian
sudo apt install ripgrep

# Arch Linux
sudo pacman -S ripgrep

Claude Code also ships with a built-in fallback, so most search operations still work even if the system ripgrep is unavailable.

Do not run sudo npm install -g @anthropic-ai/claude-code. Installing with sudo can cause permission issues with auto-updates and is a security risk. Use a version manager or configure a user-owned npm prefix instead.

Next steps

Quick Start

Run your first Claude Code session

How it works

Understand the permission model and tool system