Updated May 2026 · 10 min read

How to Install Claude Code — Mac, Linux & Windows Setup Guide

Claude Code installs as a global npm package. This guide covers every platform and all the edge cases — permission errors, PATH issues, WSL setup, API key management, and your first session.

Quick Install (3 Steps)

# 1. Install the CLI
npm install -g @anthropic-ai/claude-code

# 2. Set your API key
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# 3. Start Claude Code in your project
cd ~/my-project
claude

That's it for most setups. For the full walkthrough including API key creation and troubleshooting, continue below.

Prerequisites

Check your Node.js version: node --version. If you need to install or upgrade Node.js, use nvm (recommended) or download from nodejs.org.

Step-by-Step Installation

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

claude --version
# Should print: @anthropic-ai/claude-code 1.x.x

# For zsh (macOS default, most Linux)
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc

claude login
# Opens browser to authenticate with your Anthropic account

cd ~/my-project
claude

claude "explain what this codebase does"
claude "find all TODO comments and suggest fixes"
claude "add TypeScript types to the main functions in src/"

Platform-Specific Notes

macOS

Homebrew users: Claude Code itself isn't in Homebrew, but install Node.js with brew install node first. Then use npm to install Claude Code as shown above.

If you have multiple Node versions (via nvm), make sure you're using Node 18+: nvm use 20 before installing.

Linux (Ubuntu / Debian)

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

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

Windows (Native PowerShell)

Install Node.js for Windows from nodejs.org (LTS version). Then in PowerShell:

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

# Set API key for current session
$env:ANTHROPIC_API_KEY = "sk-ant-your-key-here"

# Set permanently in user environment
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-your-key-here", "User")

Windows with WSL2 (Recommended)

WSL2 gives you a full Linux environment. Install Ubuntu from the Microsoft Store, then follow the Linux instructions above. This is the recommended path for Windows developers — shell commands and file paths work exactly as in the documentation.

# In WSL2 Ubuntu terminal
sudo apt update && sudo apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

Troubleshooting Common Errors

EACCES: permission denied (npm install -g)

Your global npm directory requires root. Two fixes:

# Option A: Fix ownership of npm's global directory
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Option B: Reconfigure npm to use a user-writable directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

command not found: claude

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

npm config get prefix
# Returns something like /usr/local or /home/user/.npm-global

# Add /bin to PATH in your shell profile:
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc

Error: ANTHROPIC_API_KEY is not set

The environment variable isn't reaching Claude Code. Debug:

echo $ANTHROPIC_API_KEY  # Should print your key
# If empty, re-run: source ~/.zshrc (or ~/.bashrc)

In VSCode's integrated terminal, you may need to configure the terminal to launch as a login shell to inherit your profile exports.

401 Unauthorized / Invalid API key

Check that your key is correctly copied — it should be the full string starting with sk-ant-api03-. Verify it's active in console.anthropic.com under API Keys. If you created the key before adding billing, add a payment method in the console and try again.

rate_limit_error

You've hit your API rate limits. Either wait a few minutes, or consider upgrading to Claude Pro or Max for higher limits. See the pricing guide for details.

First Session Walkthrough

After installation, here's a productive 5-minute first session:

cd ~/my-project
claude

# In the Claude Code REPL:
> what tech stack is this project using?
> are there any obvious bugs or code smells in the main module?
> /help                     # see all commands
> /status                   # see what files Claude can access

What to Do Next

• Set up Claude Code in VSCode — sidebar panel, keybindings, extension config
• Learn the full commands reference — all CLI flags and REPL commands
• Create your CLAUDE.md file — project memory and conventions
• Best practices for effective sessions — how to get the most out of Claude Code

Frequently Asked Questions

How do I uninstall Claude Code?

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

Can multiple developers share one API key?

Technically yes, but not recommended. Each developer should use their own API key for security, auditing, and to avoid hitting shared rate limits. Anthropic allows multiple keys per account.

Does Claude Code need internet access to run?

Yes. All AI inference happens on Anthropic's servers. Claude Code itself runs locally but sends your prompts to the API over HTTPS. It does not work offline or in air-gapped environments.

How do I use Claude Code in a Docker container?

FROM node:20-slim
RUN npm install -g @anthropic-ai/claude-code
ENV ANTHROPIC_API_KEY=your-key
WORKDIR /project
# claude is now available as a command

→ Next: Claude Code VSCode Setup Guide

→ Claude Code Pricing — Free Tier, Pro & API Costs

← Back to Claude Code Workflows Home