Installing Claude Code

Two Ways to Install

Claude Code can be installed two ways: via npm (the Node.js package manager) or via Anthropic's installer script. Both produce the same result — a claude command available in your terminal.

Method 1: npm (Recommended)

If you already have Node.js installed:

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

This installs Claude Code globally, making the claude command available in any terminal window.

Method 2: Installer Script

If you prefer a one-line install that handles dependencies:

curl -sL https://install.anthropic.com | sh

This script detects your platform (macOS, Linux, WSL), installs Node.js if needed, and sets up Claude Code.

Requirements

Before installing, make sure you have:

• Node.js 18 or higher — check with node --version
• A supported OS — macOS, Linux, or Windows via WSL (Windows Subsystem for Linux)
• A terminal — iTerm2, Terminal.app, Windows Terminal, or any terminal emulator

If your Node.js is older than 18:

# Using nvm (Node Version Manager) — recommended
nvm install 18
nvm use 18

# Or install directly from nodejs.org
# https://nodejs.org/en/download

Authentication

This is where many new users get confused. There are two authentication methods, and which one you use determines how you're billed.

Browser Auth (Pro/Max Subscribers)

If you have a Pro ($20/mo) or Max ($100-200/mo) subscription:

1. Open your terminal

2. Run claude

3. Claude Code opens your default browser to Anthropic's login page

4. Log in with your Anthropic account

5. Approve the connection

6. Return to your terminal — you're authenticated

# First run — triggers browser authentication
claude

# You'll see something like:
# Opening browser for authentication...
# ✓ Authenticated as your@email.com (Pro plan)
# 
# Welcome to Claude Code! Type your message or /help for commands.

That's it. Your subscription covers the usage. No API keys, no billing surprises. The authentication persists across sessions until you explicitly log out.

API Key Auth (Pay-as-you-go)

If you don't have a subscription, or if you want to use Claude Code with API billing:

# Set your API key as an environment variable
export ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxx

# Now run claude
claude

You can get an API key from console.anthropic.com. API usage is billed per-token at Anthropic's published rates.

To make the key persistent across terminal sessions, add it to your shell profile:

# For zsh (default on macOS)
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxx' >> ~/.zshrc

# For bash
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxx' >> ~/.bashrc

The Critical Gotcha: API Key Overrides Subscription

This trips up a surprising number of people:

If ANTHROPIC_API_KEY is set in your environment, Claude Code uses it — even if you have an active Pro/Max subscription.

This means you'll be billed at API rates (per-token) instead of using your flat-rate subscription. If you're a subscriber and you've set an API key at some point (maybe for a different project), you need to unset it:

# Check if an API key is set
echo $ANTHROPIC_API_KEY

# If it shows a key and you want to use your subscription instead
unset ANTHROPIC_API_KEY

# To remove it permanently from your shell profile
# Edit ~/.zshrc or ~/.bashrc and remove the export line

How to tell which auth you're using: When Claude Code starts, it shows your authentication method. Look for "Pro plan" or "Max plan" vs "API key" in the startup message. You can also check with /status.

Verify Your Installation

Once installed and authenticated, verify everything is working:

# Check the version
claude --version
# Should output something like: claude-code v2.1.x

# Run diagnostics
claude doctor

The claude doctor command checks:

• Node.js version (must be 18+)
• Claude Code version (is it up to date?)
• Authentication status (are you logged in?)
• Configuration validity (is settings.json correct?)
• Network connectivity (can it reach Anthropic's API?)

If any check fails, claude doctor tells you exactly what's wrong and how to fix it.

Keeping Claude Code Updated

Claude Code updates frequently — sometimes multiple times per week with new features and fixes. Update with:

# Update to the latest version
claude update

# Or if you installed via npm
npm update -g @anthropic-ai/claude-code

It's worth updating regularly. New model capabilities, performance improvements, and bug fixes land in updates. The /status command shows your current version and whether an update is available.

Your First Run

Let's do a quick test to confirm everything works:

# Start Claude Code
claude

# Once the prompt appears, try:
"What's your model name and version?"

Claude should respond with its model information. If it does, you're fully set up.

Try a more practical test — navigate to any project directory and:

cd ~/your-project
claude

# Ask Claude about your project
"Look at the package.json and tell me what this project does"

Claude will read your package.json and give you a summary. If this works, your installation, authentication, and file access are all working correctly.

Troubleshooting Common Issues

"claude: command not found"

The global npm bin directory isn't in your PATH. Fix:

# Find where npm installs global packages
npm config get prefix
# Add that path's bin directory to your PATH
# e.g., export PATH="$HOME/.npm-global/bin:$PATH"

"Error: Node.js 18+ required"

Upgrade Node.js:

nvm install 18 && nvm use 18

"Authentication failed"

Clear stored auth and re-authenticate:

claude logout
claude
# Re-authenticate via browser

"Rate limit exceeded" immediately

Check if you accidentally have an API key set with low credits:

echo $ANTHROPIC_API_KEY
# If set, unset it to use your subscription
unset ANTHROPIC_API_KEY

Key Takeaway

Installing Claude Code is straightforward: npm install -g @anthropic-ai/claude-code or the curl installer script, then run claude to authenticate via browser. The one critical thing to remember: if ANTHROPIC_API_KEY is set in your environment, it overrides your subscription and you get billed at API rates. Run claude doctor to verify everything is healthy, and keep Claude Code updated with claude update.