TokenMix Research Lab · 2026-04-24

Claude Code Install: Clean Setup on Mac/Win/Linux 2026

Installing Claude Code — Anthropic's terminal-native AI coding agent — takes 5 minutes if nothing goes wrong. The most common failures: "zsh: command not found: claude" (PATH issue), npm global permission errors (install target), Node.js version mismatch (Claude Code needs 20+), and first-run auth timeout (corporate proxy / firewall blocking OAuth). This guide covers clean installs on Mac, Windows WSL2, and Linux — plus fixes for each common failure. Verified against Claude Code v0.25+ as of April 24, 2026. TokenMix.ai works as BYOK alternative if you want multi-provider routing.

Table of Contents

• Confirmed vs Speculation
• macOS Install (5 minutes)
• Windows WSL2 Install
• Linux Install
• Fix: "zsh: command not found: claude"
• Fix: npm install errors
• First-run: Auth + first command
• FAQ

Confirmed vs Speculation

macOS Install (5 minutes)

Prerequisites: Node.js 20+ via nvm recommended.

# Install nvm if needed
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc  # or ~/.bashrc

# Install Node 20
nvm install 20
nvm use 20

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

# Verify
claude --version

First run:

claude

Opens browser for OAuth. Authenticate with Claude.ai account (must have Pro subscription for unlimited Opus). Completes, returns to terminal.

Windows WSL2 Install

Recommended over native Windows for full compatibility.

# Install WSL2 if not already
wsl --install

# Inside WSL2 terminal
sudo apt update && sudo apt install -y curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
npm install -g @anthropic-ai/claude-code
claude

Auth OAuth flow opens Windows default browser — works with WSL2 seamlessly.

Native Windows (PowerShell) install:

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

Some features (shell integration, bash tools) work better in WSL2. Recommend WSL2 unless you need PowerShell-native.

Linux Install

# Ubuntu/Debian
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
npm install -g @anthropic-ai/claude-code
claude

Arch / Manjaro: same flow, or install Node via pacman: sudo pacman -S nodejs npm.

Fix: "zsh: command not found: claude"

Cause: npm global bin directory not in PATH.

Check global bin location:

npm config get prefix
# Returns something like /Users/you/.npm-global or /usr/local

Add to PATH in ~/.zshrc (or ~/.bashrc):

export PATH="$(npm config get prefix)/bin:$PATH"

Then reload: source ~/.zshrc.

Alternative with nvm — nvm sets PATH automatically, so the error usually means you didn't source after install or opened a new shell without nvm init.

Fix: npm install errors

Error: EACCES: permission denied → Don't sudo npm install. Configure nvm-managed Node (above) or change npm prefix:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Then re-install

Error: ERR! cb() never called → Node version too old. Must be 20+:

node --version
nvm install 20
nvm use 20

Error: gyp ERR! build error → Missing build tools. Install:

• Mac: xcode-select --install
• Ubuntu: sudo apt install build-essential

First-run: Auth + first command

claude

First run:

1. Opens browser for Anthropic OAuth
2. Log in with Claude.ai account
3. Grant access
4. Return to terminal — claude prompt ready

First prompt:

> Explain the package.json in this directory

Claude reads files in current dir, responds.

For BYOK mode (use your own API key instead of Pro subscription):

claude config set auth_method api_key
export ANTHROPIC_API_KEY="sk-ant-..."

Or route through TokenMix.ai via Claude Code Router:

export ANTHROPIC_BASE_URL="http://localhost:3456"

FAQ

Do I need a Claude Pro subscription for Claude Code?

For unlimited use of Opus 4.7 and latest features — yes, $20/mo. For pay-per-use via your own API key, BYOK mode works without Pro subscription. For the lightest path, use Claude Code Router + TokenMix.ai to pay only for tokens used.

Is there a Docker image?

Yes. docker run -it --rm anthropic/claude-code for quick try. For persistent config, mount volume: docker run -v ~/.claude:/root/.claude ....

Why did my install succeed but claude still says command not found?

PATH issue. Run npm list -g --depth=0 | grep claude to verify install. If present, fix PATH per Fix 1 above.

Can I install Claude Code on corporate locked-down Windows?

If corp restricts npm global installs: use npx @anthropic-ai/claude-code instead of installing globally. Requires internet for each run.

Does Claude Code work on Chromebooks / iPads?

Chromebooks: via Linux container (Crostini), yes. iPads: no — npm global install requires real Linux/Unix. Use web Claude.ai instead for mobile.

How do I uninstall cleanly?

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude

Removes binary and all config. OAuth token revokes on next Anthropic login.

Can I use Claude Code without internet?

No — requires API calls. For offline coding, use local models (Ollama + Continue.dev) with open-weight LLMs like GPT-OSS-120B or GLM-5.1.

Sources

• Claude Code Documentation
• Claude Code GitHub
• Claude Code Router — TokenMix
• Claude Code Routines — TokenMix
• Claude Code Pricing — TokenMix

By TokenMix Research Lab · Updated 2026-04-24