Installing Claude Code on macOS, Windows & Linux

Installing Claude Code cleanly

Most install problems come from the same three sources: wrong Node version, missing PATH on Windows, and permission errors on Linux. We'll handle all three.

Recommended install (all platforms)

# Install via npm (works everywhere)
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

If claude --version prints a version, you're done. If not, keep reading.

macOS — Homebrew alternative

brew install claude-code

Homebrew installs are the easiest to upgrade later (brew upgrade claude-code) and don't depend on your Node version.

Windows — three things to check

1. Use Node 20 LTS or later. Older Node versions silently break MCP loading. Verify with node --version.
2. Run your terminal as Administrator the first time. npm's global install needs write access to the global node_modules directory.
3. Add npm's global bin to PATH. Run npm config get prefix — the bin subdirectory needs to be on your PATH. If you use nvm-windows, this is usually %APPDATA%\npm.

Linux — avoid sudo npm

Don't fix npm permission errors with sudo npm install -g. It causes file ownership problems later. The clean fix:

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

Login

claude /login

You'll be redirected to a browser to authenticate against your Claude account. After login, your token is stored in ~/.claude/credentials.json. Don't commit this file.

Subscription vs API key

Two ways to use Claude Code:

• Subscription (Pro / Max / Team) — flat monthly fee, usage limits per 5-hour window. Best for daily coding work.
• API key — pay per token. Best for unattended jobs, Ralph loops with long runs, or production automation.

You can configure both and switch with /login. We'll cover when to prefer each in chapter 5.

Verify everything works

cd /tmp && mkdir hello-claude && cd hello-claude
claude
> echo "Hello from Claude Code" to a file called hello.txt and show the result

If a hello.txt is created and Claude prints back the contents, you're fully set up.

Try it

Install Claude Code, log in, and run the verify step above. Confirm in the chapter discussion when you've completed it.