How to Install Claude Code (2026): macOS, Windows & Linux, Plus Fixes for Common Errors

We installed Claude Code 2.1.300 on a clean Apple-silicon Mac on October 15, 2026, using the native installer, npm and Homebrew, and the outputs below are copied from those runs. We didn't have a Windows or Linux machine for this test, so those steps follow Anthropic's official documentation and are marked where it matters.

Pick an install method

All of these install the same program. What differs is where it downloads from and whether it keeps itself up to date.

Before you install

• Operating system: macOS 13 or later, Windows 10 version 1809 or later (or Windows Server 2019+), Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+. It must be a 64-bit system.
• Hardware: 4 GB of RAM or more, with an x64 or ARM64 processor. Apple-silicon Macs are fine.
• Node.js: not required. Plenty of older tutorials start with "install Node.js first". That was true when npm was the only way to install Claude Code, and it isn't anymore. You need Node.js 22+ only for the npm method.
• A way to pay for the model. The CLI is free, but it does nothing without access to Claude: a Pro, Max, Team or Enterprise plan, a Claude Console account, a cloud provider, or an API gateway. The free Claude plan doesn't include Claude Code. Sign in or use an API key compares the options.

Install on macOS and Linux

Open Terminal and run:

curl -fsSL https://claude.ai/install.sh | bash

The script prints nothing while it downloads, so give it a moment. On our Mac it took 25 seconds and finished with:

✔ Claude Code successfully installed!

  Version: 2.1.300

  Location: ~/.local/bin/claude

  Next: Run claude --help to get started

If ~/.local/bin isn't on your PATH yet, the installer warns you and prints the exact line to fix it. Run that line before going further (it's also covered in command not found).

Native installs check for updates in the background and update themselves, so you can mostly forget about them.

Install on Windows (no WSL needed)

Claude Code runs natively on Windows. You only need WSL if your projects already live there or you want sandboxed command execution:

Check which shell you opened. If the prompt starts with PS, as in PS C:\Users\you>, you're in PowerShell. Without PS, it's Command Prompt (CMD). The two need different commands, and mixing them up is the most common Windows install error.

In PowerShell:

irm https://claude.ai/install.ps1 | iex

In CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

You don't need to run either as Administrator. When it finishes, open a new terminal and run claude --version.

Git for Windows is optional but worth installing. With Git for Windows, Claude Code runs shell commands through Git Bash. Without it, it falls back to PowerShell. If Git is installed somewhere unusual and Claude Code can't find Git Bash, point to it in %USERPROFILE%\.claude\settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Using WSL instead? Open your WSL distribution and run the macOS/Linux command above inside it. Install and launch claude from the WSL terminal, not from PowerShell or CMD.

Other ways to install

Homebrew (macOS)

brew install --cask claude-code

Two things to know:

1. The claude-code cask follows the stable channel, so it lags behind. When we checked, the latest release was 2.1.300 and Homebrew had 2.1.287. For the newest build, install claude-code@latest instead.
2. Homebrew installs don't update themselves. Run brew upgrade claude-code (or brew upgrade claude-code@latest) from time to time.

WinGet (Windows)

winget install Anthropic.ClaudeCode

Like Homebrew, it won't update on its own. Run winget upgrade Anthropic.ClaudeCode periodically.

Linux package managers (apt, dnf, apk)

Anthropic publishes signed repositories, which suit servers and teams that want Claude Code to update with the rest of the system. On Debian or Ubuntu, using the stable channel:

sudo apt install curl gnupg
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc -o /etc/apt/keyrings/claude-code.asc
gpg --show-keys /etc/apt/keyrings/claude-code.asc

The fingerprint must read 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. If it does, add the repository and install:

echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

On Fedora or RHEL:

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

For the latest channel, replace stable with latest in the repository URL (for apt, in both places on the deb line). Alpine has an apk repository too; see Anthropic's setup guide.

npm

This needs Node.js 22 or later. Check with node -v, then:

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

npm adds two packages, the small @anthropic-ai/claude-code wrapper and the native binary for your platform. It's the same binary the native installer downloads, and it doesn't use Node.js once it's installed:

added 2 packages in 7s

To update an npm install, run npm install -g @anthropic-ai/claude-code@latest. Avoid npm update -g, which may not move you to the newest version.

Verify the install

Close the terminal, open a new one, and check the version:

claude --version

2.1.300 (Claude Code)

Then run the built-in health check. It inspects the installation without starting a session:

$ claude doctor
Claude Code doctor

Running: native (2.1.300)
Platform: darwin-arm64
Config install method: native
Search: OK (bundled)
…

The lines worth reading are Running (which install is actually running, which matters if you have two), Search (Claude Code's bundled ripgrep, which powers file search) and Auto-updates. Any problem ends up in a warnings list at the bottom with a Fix: line telling you what to do. Inside a session, /doctor runs a fuller check that can repair some issues itself.

Sign in or use an API key

Go to a project folder and start Claude Code:

cd your-project
claude

The first launch asks you to pick a color theme and then how to authenticate. Choose based on how you want to pay:

Subscription and Console logins save your credentials, so you only do this once. To switch later, run /login inside a session. /status shows which credential is in use.

Use an API gateway

Claude Code officially supports sending its requests to an LLM gateway instead of directly to Anthropic. You set two variables and skip the login entirely. Put them in ~/.claude/settings.json (Windows: %USERPROFILE%\.claude\settings.json) so the CLI and the VS Code extension both pick them up.

Here's the setup for api.foo, the gateway that publishes these docs. Any Anthropic-compatible gateway works the same way with its own URL and key:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.foo",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key"
  }
}

Save the file, then run claude again. A few details that trip people up:

• ANTHROPIC_AUTH_TOKEN vs ANTHROPIC_API_KEY. The first sends your key as Authorization: Bearer, which is what gateways expect. The second sends it as X-Api-Key and is meant for Claude Console keys. It also asks you once to approve the key, and once approved it overrides a subscription login. api.foo accepts both, but ANTHROPIC_AUTH_TOKEN is the cleaner choice for a gateway.
• The base URL alone isn't enough. If you set ANTHROPIC_BASE_URL but no key, requests go through the gateway but still carry your saved Claude login, so your plan's limits and billing still apply.
• Leave off /v1. Claude Code appends the API path itself. api.foo also accepts https://api.foo/v1, but many gateways don't.
• Long-running jobs: api.foo has a direct route, https://dc.api.foo, that bypasses the 100-second proxy timeout on the default address. Use it as the base URL if long tasks get cut off.
• Claude models only. Anthropic doesn't support pointing Claude Code at non-Claude models through a gateway. Some gateways let you do it, but expect broken tool use and odd behavior.

For model mapping, the VS Code extension, Claude Code Router and the errors you might hit, see Claude Code with a custom API or base URL.

Use Claude Code in VS Code or Cursor

Anthropic's VS Code extension gives Claude Code a graphical panel with inline diffs, plan review and conversation tabs.

1. Make sure you have VS Code 1.94 or later.
2. Open the Extensions view (Cmd+Shift+X on Mac, Ctrl+Shift+X on Windows/Linux), search for Claude Code by Anthropic (anthropic.claude-code), and install it.
3. Click the Claude icon to open the panel and sign in.

Cursor and other VS Code forks such as Kiro install the same extension through the Open VSX registry: search for "Claude Code" in their Extensions view.

Keep these in mind:

• The extension doesn't install the claude command. It bundles a private copy of Claude Code for its panel. To use the CLI in VS Code's integrated terminal, install it with any method above. Once installed, the CLI connects to the editor automatically for diffs and diagnostics.
• If claude runs in an external terminal, type /ide inside the session to connect it to your editor.
• If you use an API gateway, the extension reads the same ~/.claude/settings.json. If it still asks you to sign in, open VS Code settings, search for "Claude Code login" and turn on Disable Login Prompt.
• The CLI and the extension share conversation history. claude --resume in a terminal picks up a conversation you started in the panel.

Fix common install errors

Find the message you're seeing.

command not found: claude or "'claude' is not recognized"

zsh: command not found: claude

Claude Code is installed, but the folder it went into isn't on your PATH. We reproduced this on a fresh install. Pick the line for your shell:

# macOS (zsh, the default shell)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Linux (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

On Windows, in PowerShell:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Then open a new terminal. Windows already open keep the old PATH. A terminal inside VS Code or Cursor inherits the editor's PATH, so quit and reopen the editor too. For npm installs, the folder that needs to be on PATH is the bin directory under npm config get prefix (on Windows, the prefix directory itself).

syntax error near unexpected token '<' or curl: (22) ... error: 403

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

The install URL returned a web page instead of the script, and bash tried to run the HTML. If the output mentions "App unavailable in region", Claude Code isn't offered in your country. Otherwise it's usually a corporate proxy, a firewall or a captive Wi-Fi portal intercepting the download. Retry in a few minutes or on another network. If you're behind a proxy, set it before running the installer:

export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

If your network only blocks claude.ai, the npm method downloads from the npm registry instead.

Failed to fetch version from downloads.claude.ai

The installer got the script but can't reach Anthropic's download server. It has the same causes and the same fixes as the error above. Corporate networks often need downloads.claude.ai allowlisted.

'irm' is not recognized or The token '&&' is not a valid statement separator

You ran the command for the other Windows shell:

• 'irm' is not recognized: you're in CMD. Use the CMD command.
• '&&' is not a valid statement separator: you're in PowerShell. Use the PowerShell command.

running scripts is disabled on this system (npm on Windows)

PowerShell's execution policy is blocking the .ps1 launchers npm creates. Allow local scripts for your account:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

You can also run claude.cmd instead of claude, or switch to the PowerShell native installer, which doesn't use a .ps1 launcher.

Claude Code does not support 32-bit Windows

On a 64-bit PC this usually means you opened Windows PowerShell (x86) from the Start menu. Open the plain Windows PowerShell entry and run the installer again. If [Environment]::Is64BitOperatingSystem prints False, your Windows is 32-bit and can't run Claude Code.

claude opens the Claude desktop app (Windows)

Older versions of Claude Desktop register a Claude.exe that takes priority on PATH. Update Claude Desktop to the latest version.

Killed or exit code 137 on a small Linux server

The installer needs about 512 MB of free memory, and the Linux out-of-memory killer stopped it. This is common on 1 GB VPS plans. Add 2 GB of swap and run the installer again:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Error: claude native binary not installed (npm)

npm skipped the platform-specific package that holds the actual program. Check whether you installed with --omit=optional or --ignore-scripts, or have optional=false in .npmrc. Remove that and reinstall:

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

EACCES permission errors with npm

Don't reach for sudo. The simplest fix is to use the native installer, which installs into your home folder and never touches npm's global directory. If you need npm, move its global directory into your home folder:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Installing Node.js with a version manager such as nvm avoids the problem too.

Update, switch channels or uninstall

Updating:

Switching to the stable channel on a native install: add "autoUpdatesChannel": "stable" to ~/.claude/settings.json. To turn background updates off completely, set "DISABLE_AUTOUPDATER": "1" in its env block. claude doctor then shows auto-updates as disabled.

Uninstalling:

# Native installer (macOS, Linux, WSL)
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

# Homebrew
brew uninstall --cask claude-code

# apt / dnf
sudo apt remove claude-code
sudo dnf remove claude-code

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

Windows, in PowerShell:

# Native installer
Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

# WinGet
winget uninstall Anthropic.ClaudeCode

Removing the program leaves your settings and conversation history in place. For a completely clean slate, also delete the ~/.claude folder and the ~/.claude.json file, after checking there's nothing in them you want to keep. If the VS Code extension or Claude Desktop is still installed, they'll recreate that folder next time they run.

What to do next

Run /init in your first session. Claude Code reads the project and writes a CLAUDE.md file describing how it's built and run, and it re-reads that file at the start of every session, which makes its answers noticeably more accurate. After that, describe a real task in plain English. "Fix the login page going blank after a wrong password" works much better than "fix the bug".