Install Claude Code: The Complete Guide for macOS, Windows & Linux (July 2026)

The 3 Commands

Anthropic's recommended method is the native installer. It needs no Node.js and auto-updates in the background.

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

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

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

Then verify and start:

claude --version   # confirm the binary is on your PATH
cd your-project
claude             # first launch opens browser auth

Is Claude Code Free to Install?

Installing is free. Using it is not. Claude Code requires one of: a Claude Pro plan ($17/month billed annually, $20 monthly), Max 5x ($100/month), Max 20x ($200/month), Team ($20/seat/month annual standard), Enterprise, or an Anthropic Console account billed per token at API rates. Anthropic's setup docs state it directly: the free Claude.ai plan does not include Claude Code access.

Claude Code also works through Amazon Bedrock, Google Vertex AI, and Microsoft Foundry if your organization already buys Claude there. Full plan breakdown on our Claude Code pricing page; session and weekly caps on Claude Code usage limits.

System Requirements

• macOS: 13.0 or newer
• Windows: 10 version 1809+ or Server 2019+
• Linux: Ubuntu 20.04+, Debian 10+, or Alpine 3.19+
• Hardware: 4 GB+ RAM, x64 or ARM64
• Shell: Bash, Zsh, PowerShell, or CMD
• Node.js 22+: only for the npm install method (the floor moved from 18 to 22 in v2.1.198)

Alpine and other musl-based distros additionally need libgcc, libstdc++, and ripgrep, with USE_BUILTIN_RIPGREP=0 set.

All 6 Install Methods Compared

There is also a Desktop app (graphical, no terminal) for macOS and Windows at claude.com/download, plus a VS Code extension and JetBrains plugin. The CLI underpins all of them.

Install Claude Code on macOS and Linux (curl)

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

This installs the binary to ~/.local/bin/claude and adds it to your PATH. Open a new terminal window afterward so your shell picks up the PATH change, then run claude --version.

Works identically inside WSL. No sudo, no Node.js, no package manager.

irm https://claude.ai/install.ps1 | iex (Windows)

That PowerShell one-liner is the entire Windows install. irm (Invoke-RestMethod) downloads the install script, iex (Invoke-Expression) runs it:

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

From CMD instead:

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

Or via WinGet:

winget install Anthropic.ClaudeCode

Windows specifics worth knowing:

• No admin rights needed. Native Windows installs run as a regular user.
• Git for Windows is optional but enables the Bash tool. Without it, Claude Code uses the PowerShell tool. If Git Bash is installed but not found, set CLAUDE_CODE_GIT_BASH_PATH (e.g. C:\Program Files\Git\bin\bash.exe) in your settings env.
• Sandboxing: WSL2 is supported; native Windows and WSL1 are not.

WSL Install

# In PowerShell (admin), then reboot:
wsl --install

# Inside your WSL terminal:
curl -fsSL https://claude.ai/install.sh | bash

Common WSL mistake: installing via npm with Node.js present on the Windows side but not inside WSL. Each environment needs its own install. The native curl method inside WSL sidesteps this entirely.

Install Claude Code on Ubuntu, Debian, Fedora, and Alpine

Beyond the curl installer, Anthropic publishes signed apt, dnf, and apk repositories at downloads.claude.ai. For Ubuntu and Debian:

# Add Anthropic's signing key
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

# Add the stable repository
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

# Upgrade later with:
# sudo apt update && sudo apt upgrade claude-code

Fedora/RHEL use a dnf repo with baseurl https://downloads.claude.ai/claude-code/rpm/stable; Alpine uses the apk repo at https://downloads.claude.ai/claude-code/apk/stable. The GPG key fingerprint is 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE, so you can verify what you are trusting.

More distro detail on our Claude Code on Linux page.

Brew Install Claude Code (macOS)

brew install --cask claude-code

# Or track the newest release instead of stable:
brew install --cask claude-code@latest

Two caveats. The default cask follows the stable channel, about one week behind the latest release. And Homebrew installs do not auto-update:

brew upgrade claude-code

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

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

As of v2.1.198 this requires Node.js 22+ (it was 18+ for most of 2025). On older Node, npm prints an EBADENGINE warning rather than failing; the install still completes and claude still runs, because the package downloads a native binary that never touches your Node at runtime. The binary arrives through per-platform optional dependencies like @anthropic-ai/claude-code-darwin-arm64, linked into place by a postinstall step. So npm is a delivery mechanism, not a runtime dependency. Use it when npm is already your standard tooling or you pin versions in lockstep with a team. Full npm walkthrough: npm install claude code.

Upgrade explicitly, not with npm update -g:

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

Migrate From an Old npm Install to the Native Installer

Through most of 2025, Claude Code shipped as an npm package that ran on your Node. It is now a native binary, and Anthropic recommends the native install. If you installed the old way, run the migration from inside Claude Code:

# Inside a running Claude Code session:
/migrate-installer

# Or from the shell:
claude install

The single most common post-migration failure is the old npm binary shadowing the native one on your PATH. After migrating, remove the npm copy so which claude resolves to ~/.local/bin/claude, not a Node shim:

npm uninstall -g @anthropic-ai/claude-code
hash -r            # bash: forget the cached path (use rehash in zsh)
which claude       # should now print ~/.local/bin/claude
claude doctor      # confirms install type is 'native'

Verify the Install

claude --version   # binary found and on PATH
claude doctor      # detailed config check: install type, auth, settings
claude update      # apply any pending update immediately

If claude --version prints a version, the install worked. claude doctor is the first thing to run when anything misbehaves later; it diagnoses installation type, auth state, and configuration issues.

Authentication: Subscription vs API Key

Run claude in a project directory. First launch opens your browser to authenticate. Two paths:

Subscription auth signs in with your Claude.ai account; usage draws from your plan's five-hour session limit plus weekly caps, shared with Claude chat. Console auth bills per token: Opus 4.6 at $5/$25 per million tokens, Sonnet 4.6 at $3/$15, Haiku 4.5 at $1/$5. For headless and CI environments, set ANTHROPIC_API_KEY instead of browser auth.

Enterprise setups can route through Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI (CLAUDE_CODE_USE_VERTEX=1), or an LLM gateway; see Claude Code with LiteLLM.

Run Local or Open-Weight Models in Claude Code

The install is the same regardless of which model answers. Claude Code reads two environment variables, ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, so it can point at any OpenAI/Anthropic-compatible endpoint instead of Anthropic's API. That covers a local Ollama server, an LiteLLM gateway, or a hosted open-weight endpoint.

Morph serves open-weight coding models on custom kernels behind an OpenAI-compatible API at https://api.morphllm.com/v1: GLM-5.2 (morph-glm52-744b, 1M context), Qwen 3.5 397B (morph-qwen35-397b, 256k), and DeepSeek V4 Flash (morph-dsv4flash, 1M context at $0.139 in / $0.278 out per million tokens). Wire one in:

export ANTHROPIC_BASE_URL="https://api.morphllm.com/v1"
export ANTHROPIC_AUTH_TOKEN="$MORPH_API_KEY"
export ANTHROPIC_MODEL="morph-glm52-744b"
claude

The routing pattern and its limits (which Anthropic-specific tools degrade behind non-Anthropic models) are covered on use a different LLM in Claude Code and Claude Code with Ollama. The full open-weight lineup with per-token pricing is on Morph models.

Pin a Version, Control Updates

# Exact version
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

# Stable channel (about a week behind latest)
curl -fsSL https://claude.ai/install.sh | bash -s stable

# Windows PowerShell, stable channel
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

Control the update channel in settings.json:

{
  "autoUpdatesChannel": "stable"
}

autoUpdatesChannel defaults to latest. Set the env var DISABLE_AUTOUPDATER=1 to stop background updates, or DISABLE_UPDATES to block every update path. Teams can enforce a floor with minimumVersion.

Uninstall Claude Code

# Remove the binary and shared files
rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude

# Optionally remove all settings, MCP config, and session history
rm -rf ~/.claude && rm ~/.claude.json

Homebrew, WinGet, npm, and apt installs uninstall through their respective package managers. The second command deletes your configuration permanently; skip it if you plan to reinstall.

Troubleshooting

The failures below cover most first-run installs. For the full catalog of install errors, including npm EACCES edge cases, PATH resolution on every shell, WSL, and Windows-specific failures, see the dedicated Claude Code install errors guide.

claude: command not found

The native installer puts the binary at ~/.local/bin/claude. Open a new terminal first. Still missing? Check that ~/.local/bin is on your PATH; this is the most common failure on Ubuntu and WSL:

# Check where (or whether) claude resolves
which claude
ls ~/.local/bin/claude

# If the binary exists but isn't found, add it to PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc
source ~/.bashrc

EACCES errors with npm

Do not reach for sudo. Point npm's global prefix at a directory you own, or use nvm:

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

Authentication fails

• Confirm your account is Pro, Max, Team, Enterprise, or Console. The free plan is rejected.
• Make sure the browser that opens is logged into the same Claude account.
• Run claude logout, then claude to retry.
• In CI or on servers, set ANTHROPIC_API_KEY instead.

Alpine: binary runs but tools fail

musl-based distros need libgcc, libstdc++, and system ripgrep, plus USE_BUILTIN_RIPGREP=0. On Alpine: apk add libgcc libstdc++ ripgrep.

EBADENGINE or Node crashes on npm install

The npm package requires Node.js 22+ as of v2.1.198. On older Node you get an EBADENGINE warning (install still completes); on Node 18 some builds crash with TypeError: Object not disposable (issue #26942). Fix: nvm install 22 && nvm use 22, or skip Node entirely with the native installer.

Corporate proxy or TLS certificate errors

unable to get local issuer certificate, SELF_SIGNED_CERT_IN_CHAIN, or a blocked download usually means a proxy is inspecting your traffic. Point the installer at the proxy and your company's CA:

export HTTPS_PROXY=http://proxy.example.com:8080
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem
curl -fsSL https://claude.ai/install.sh | bash

WSL calls the Windows node instead of the Linux one

Windows PATH leaks into WSL, so claude in WSL can pick up node.exe from the Windows side. Prepend your Linux Node to PATH in ~/.bashrc:

export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"

If claude in WSL prints cannot execute binary file: Exec format error, you are on WSL1, which cannot run the native binary. Use WSL2, or install inside a real Linux environment.

Two installs fighting: claude runs the wrong version

After migrating or reinstalling, an old npm binary or shell alias can shadow the native install. Find which one wins and remove the stale copy:

which -a claude          # lists every claude on PATH
type claude              # shows an alias if one is set
npm uninstall -g @anthropic-ai/claude-code   # remove the npm copy if present
hash -r                  # forget the cached path (rehash in zsh)
claude doctor            # 'Installation type' confirms which one is active

Browser login callback never returns

If first-launch auth hangs, the localhost callback is likely blocked. Copy the URL Claude Code prints, finish login in any browser, and paste the returned code back into the terminal. On headless servers or CI, set ANTHROPIC_API_KEY and skip browser auth entirely.

Everything else

claude doctor diagnoses install type, auth, and config issues automatically. Run it before debugging by hand.

After Install: Generate a CLAUDE.md

The highest-impact post-install step takes one command. Inside Claude Code, run /init. It analyzes your codebase and generates a starter CLAUDE.md: build commands, conventions, and architecture notes that load into every session. Anthropic's guidance is to keep it under 200 lines and make every instruction verifiable ("Run npm test before committing", not "test thoroughly").

/init

Structure and examples: CLAUDE.md guide and CLAUDE.md examples. From there, the usual extension points are MCP servers, hooks, and settings.json permissions.

Frequently Asked Questions

Can I install Claude Code for free?

Installing costs nothing. Using it requires a paid plan: Pro ($17/mo annual, $20 monthly), Max ($100-200/mo), Team, Enterprise, or a Console account billed at API rates. The free Claude.ai plan does not include Claude Code.

Do I need to install Claude Code to use Claude for coding?

No. Claude Code also ships as a Desktop app for macOS and Windows (graphical, no terminal), a VS Code extension, and a JetBrains plugin. The CLI is the most capable surface, but the desktop app needs no terminal at all.

Does Claude Code require Node.js?

Only the npm install method, and only at install time (Node.js 18+). The package delivers a native binary via platform-specific optional dependencies; the claude command never invokes Node. Native, Homebrew, WinGet, and apt installs skip Node entirely.

What is the difference between the curl installer and npm?

Same binary, different update behavior. The native curl/PowerShell install auto-updates in the background. The npm install updates only when you run npm install -g @anthropic-ai/claude-code@latest.

Can I use Claude Code on Windows without WSL?

Yes. irm https://claude.ai/install.ps1 | iex installs natively, no admin rights required. Install Git for Windows if you want Claude to use Bash instead of PowerShell. The one feature gap: sandboxing requires WSL2.

How do I update Claude Code?

claude update applies updates immediately on any install. Native installs also auto-update in the background. Homebrew: brew upgrade claude-code. WinGet: winget upgrade Anthropic.ClaudeCode. npm: reinstall with @latest (avoid npm update -g).

How do I install an older or pinned version?

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89 installs that exact version. bash -s stable tracks the stable channel. Set {"autoUpdatesChannel": "stable"} in settings.json to stay there.

What are the system requirements for Claude Code?

macOS 13.0+, Windows 10 1809+/Server 2019+, or Ubuntu 20.04+/Debian 10+/Alpine 3.19+; 4 GB+ RAM; x64 or ARM64; and a Bash, Zsh, PowerShell, or CMD shell. Node.js is only needed for the npm method (22+ as of v2.1.198). The native installer needs no Node.js.

How do I migrate from an npm install to the native installer?

Run /migrate-installer inside Claude Code, or claude install from the shell. Then npm uninstall -g @anthropic-ai/claude-code and hash -r so the old npm binary stops shadowing the native one. claude doctor confirms the active install type.

Can I run local or open-source models in Claude Code?

Yes. Set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN to any OpenAI/Anthropic-compatible endpoint, whether a local Ollama server, a LiteLLM gateway, or a hosted open-weight endpoint. See using a different LLM and Morph models for the routing pattern and its tool-support caveats.

Is the claude CLI the same thing as Claude Code?

Yes. claude is the command the Claude Code install provides. Run it bare for the interactive REPL, or claude -p "prompt" for non-interactive scripted use.