Installing Across Every Platform

Before any command, hold one question in your head: after I install, who is responsible for keeping Claude Code up to date — Claude Code, or me?

That single distinction sorts every install method into two camps:

• Native installers auto-update. The curl ... | bash / irm ... | iex / install.cmd installers (and the npm package, which pulls the same native binary) check for updates on startup and periodically while running, download in the background, and apply the new version next launch. You do nothing.
• Package managers do NOT auto-update. Homebrew, WinGet, apt, dnf, and apk all hand update responsibility back to you. They install a binary and walk away. If you never run an upgrade command, you stay frozen on the version you installed — potentially for months — missing features and security fixes.

Everything else in this lesson — channels, version pinning, verification — hangs off that frame. Pick a method knowing which camp it's in, and you'll never be mysteriously stuck on an old version.

Claude Code is the same agentic tool regardless of how you install it; the install method only changes delivery and updates, never the product.

Claude Code runs on these platforms. If you're below a minimum OS version, upgrade the OS first — installs on unsupported systems fail in confusing ways.

A few load-bearing notes:

• Claude Code is not on the free tier. Installing it is free; using it requires a Pro, Max, Team Premium, Enterprise, or Console account (or a cloud provider like Bedrock/Vertex/Foundry). A free Claude.ai account cannot authenticate.
• ripgrep ships with Claude Code on most platforms. The exception is Alpine/musl — covered later.
• On Windows you choose native vs WSL: native Windows for Windows-native projects and tools; WSL 2 when you want Linux toolchains or sandboxed command execution. You install Claude Code inside whichever environment your projects live in.

The native installer is the recommended path on every platform. It auto-updates, needs no Node.js, and installs a standalone binary. Pick the line for your shell.

macOS, Linux, WSL (run inside the WSL terminal for WSL):

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

Windows PowerShell:

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

Windows CMD:

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

How do you know which Windows shell you're in? Your prompt shows PS C:\... in PowerShell and C:\... without the PS in CMD. If && errors with "The token '&&' is not a valid statement separator," you ran the CMD line in PowerShell. If 'irm' is not recognized, you ran the PowerShell line in CMD.

After it finishes, launch Claude Code from any terminal by opening your project and running:

claude

You do not need Administrator on Windows, and you should never run the macOS/Linux installer with sudo.

Prefer your OS package manager? Every major one is supported. Remember the mental model: none of these auto-update by default.

Homebrew (macOS)

Homebrew offers two casks, and the choice is your channel selection:

brew install --cask claude-code         # stable channel (~1 week behind)
brew install --cask claude-code@latest  # latest/rolling channel

Upgrade manually with brew upgrade claude-code (or brew upgrade claude-code@latest). Homebrew keeps old versions on disk — run brew cleanup occasionally to reclaim space.

WinGet (Windows)

winget install Anthropic.ClaudeCode

Upgrade with winget upgrade Anthropic.ClaudeCode. This can fail while Claude Code is running because Windows locks the executable — close Claude Code first, then upgrade.

npm (cross-platform, needs Node.js 18+)

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

The npm package installs the same native binary as the standalone installer (via a per-platform optional dependency); the installed claude does not itself run Node. To upgrade, run npm install -g @anthropic-ai/claude-code@latest — not npm update -g, which respects the original semver range and may not move you to the newest release.

Linux package managers (apt / dnf / apk)

Claude Code publishes signed apt, dnf, and apk repositories. The simplest forms:

sudo apt update && sudo apt install claude-code   # Debian / Ubuntu
sudo dnf install claude-code                       # Fedora / RHEL
apk add claude-code                                # Alpine

These pull from Claude Code's signed repos (you add the signing key and repo line once — see the official setup page for the full repository setup). Updates arrive through your normal system upgrade workflow (e.g. sudo apt update && sudo apt upgrade claude-code), not through Claude Code.

Claude Code ships on two channels:

• latest (default) — new features the moment they're released.
• stable — a version typically about one week old, which skips releases with major regressions. Great for teams that value predictability over bleeding-edge.

With the native installer, the channel you choose at install time becomes your auto-update default:

curl -fsSL https://claude.ai/install.sh | bash            # latest (default)
curl -fsSL https://claude.ai/install.sh | bash -s stable  # stable channel
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89  # exact version

The PowerShell equivalents pass the argument through a script block, e.g. & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable.

After install, switch channels with the autoUpdatesChannel setting (via /config -> Auto-update channel, or in settings.json):

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

minimumVersion sets a floor: auto-updates and claude update refuse to install anything below it, so moving from latest to stable won't downgrade you if you're already ahead. With Homebrew, the cask name is the channel (claude-code = stable, claude-code@latest = latest) — the autoUpdatesChannel setting doesn't apply there.

To force an update right now without waiting for the background check, run claude update.

Two commands confirm a healthy install on every platform:

claude --version   # prints the version number
claude doctor      # deep install/config diagnostics

If claude --version errors with command not found, your shell hasn't picked up the binary's directory on PATH yet — open a new terminal, or check the troubleshooting docs. claude doctor goes further: it reports the result of the most recent update attempt (invaluable when you suspect an auto-update silently failed) and lists fixes for common problems like a non-writable npm global directory.

Alpine Linux / musl: extra steps

Alpine (and other musl/uClibc-based distros) is the one platform where the native installer needs help. It requires three extra packages, and you must tell Claude Code to use the system ripgrep instead of its bundled one:

apk add libgcc libstdc++ ripgrep

Then set USE_BUILTIN_RIPGREP to 0 in the env block of settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Skip either step on Alpine and you'll see the binary fail to start, or in-session code search break.