How to Install Claude Code: macOS, Windows, Linux, and WSL (2026)

Priya had Claude Code installed three times before she noticed. She'd started with npm in March, added the Homebrew cask when a tutorial suggested it, then ran the official installer in June after an update failed silently. For six weeks she was running a version two months behind whatever claude --version told her, because her shell was resolving a stale binary first. One claude doctor would have caught it on day one. You already know installing a CLI is supposed to be the easy part, so here's the version that stays easy: the single command that covers most people, the five install methods and what each one costs you in maintenance, the Windows fork in the road, and the four checks that prove the thing actually works before you waste an afternoon on a phantom bug.

The One-Line Install (and What It Actually Does)

The recommended way to install Claude Code is the native installer, a single command that downloads a self-contained binary for your platform. On macOS, Linux, and WSL:

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

On Windows PowerShell:

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

On Windows CMD:

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

On macOS and Linux this puts a launcher at ~/.local/bin/claude that symlinks into ~/.local/share/claude/versions/. That layout is the reason native installs can update themselves: new versions land in the versions/ directory and the launcher points at the current one. Nothing is installed system-wide, and you never need sudo.

Then open a terminal inside the project you want to work in and start it:

claude

System requirements are modest: macOS 13.0 or later, Windows 10 build 1809 or later, Ubuntu 20.04+, Debian 10+, or Alpine 3.19+, with 4 GB of RAM and an x64 or ARM64 processor. If your first session works, the next thing worth doing is browsing the skill registry to see what capabilities you can drop into it, since a fresh install ships with none of your team's conventions in it yet.

Pick Your Install Method

Five install paths are supported, and they differ in exactly one way that matters after installation day: whether they keep themselves current. Claude Code ships changes constantly, and a version four weeks stale can be missing flags that tutorials assume you have.

Homebrew publishes two casks, and the distinction trips people up. claude-code follows the stable channel, which runs roughly a week behind and skips releases with major regressions. claude-code@latest takes every release the day it ships. Your upgrade command has to match the cask you installed, so brew upgrade claude-code does nothing for someone on the @latest cask.

The npm path deserves one clarification, because it causes more confusion than the other four combined. Installing through npm does not mean Claude Code runs on Node. npm pulls in a per-platform optional dependency such as @anthropic-ai/claude-code-darwin-arm64 and links the native binary into place; the resulting claude never invokes Node at runtime. Node.js 22 or later is needed only for npm itself to do the install. On an older Node you'll see an EBADENGINE warning, the install completes anyway, and claude still runs. Never install it with sudo npm install -g, which creates permission problems that outlive the install.

Linux users who want package-manager governance can add Anthropic's signed apt, dnf, or apk repositories. Each offers a stable and a latest channel, and all are signed with the release key whose fingerprint is 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. Verify that fingerprint before trusting the key; it takes one gpg --show-keys and it's the difference between a signed supply chain and a hopeful one.

Windows: Native or WSL?

Windows is the only platform where you have to make a real decision, and picking wrong costs you a feature rather than an afternoon.

Sandboxing is the deciding factor. It isolates the filesystem and network for shell commands, and it only exists under WSL 2. If you plan to let the agent run commands with any autonomy, that isolation is worth relocating your project for. The permission modes guide covers how sandboxing interacts with the mode you run in.

On native Windows, run the installer from PowerShell or CMD without Administrator rights. Installing Git for Windows is optional but changes what Claude Code can do: with it, the agent uses Git Bash for its Bash tool; without it, it falls back to the PowerShell tool. If Git Bash is installed somewhere unusual, point at it in settings.json:

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

One error message tells you which shell you're actually in. If the CMD one-liner returns The token '&&' is not a valid statement separator, you're in PowerShell. If irm comes back as "not recognized as an internal or external command," you're in CMD. Your prompt shows PS C:\ in PowerShell and C:\ without it in CMD.

Prove the Install Worked

Two commands separate "installed" from "working," and skipping them is how Priya lost six weeks. Start with the version:

claude --version

A working install prints something like 2.1.211 (Claude Code). Then run the diagnostic:

claude doctor

claude doctor prints read-only diagnostics without starting a session: install health, settings-file validation errors, the result of the most recent update attempt, and warnings with suggested fixes. It also reports a launcher that the native installer didn't create, which is exactly the signal that catches a competing installation. Run it once after installing and again any time the CLI behaves in a way that doesn't match the docs.

Log In: What Plan You Actually Need

Here's the part the install guides bury, and it's the single most common reason a successful install still can't run: the free Claude.ai plan does not include Claude Code. You need a Pro, Max, Team, or Enterprise subscription, or a Claude Console API account. Companies routing inference through their own cloud can authenticate via Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry instead.

Logging in is just running claude and following the browser prompt. If the ANTHROPIC_API_KEY environment variable is already set, Claude Code prompts once to approve that key rather than opening a browser. Which route is cheaper depends entirely on how much you use it, and the Claude Code pricing breakdown walks through the subscription-versus-API math with real monthly numbers.

Staying Updated, or Deliberately Not

Native installs check for updates at startup and periodically while running, download in the background, and apply the new version the next time you launch. To pull one immediately:

claude update

You can also choose how aggressive updates are. The autoUpdatesChannel setting takes "latest" (the default, new features the day they ship) or "stable" (about a week behind, skipping releases with major regressions):

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

minimumVersion sets a floor, so moving to the stable channel can't quietly downgrade a machine that's already ahead of it. In managed settings, an administrator can enforce that floor across an organization.

Marcus, who runs platform tooling for a 40-engineer team, pinned everyone to "stable" after a mid-sprint release changed a flag his CI scripts depended on. His rule now is that individual developers run latest and anything automated runs stable, which costs one settings file and has held for four months. If you distribute Claude Code through your own channels and need versions frozen entirely, set DISABLE_AUTOUPDATER to "1" in the env key of settings.json, or DISABLE_UPDATES to block manual updates too. Once you're pinning versions, it's worth pinning behavior as well, and installing your team's skills from a scanned registry is the same instinct applied one layer up.

When the Install Goes Wrong

Four failures cover almost everything people hit, and each has a specific fix rather than a reinstall.

Multiple installations fighting. This is Priya's bug, and it's the one that wastes the most time because everything appears to work. If claude --version disagrees with what you just installed, you have a second copy or a leftover shell alias from an older installer earlier in your PATH. claude doctor flags a launcher it didn't create. Remove the duplicate rather than reinstalling on top of it.

The npm global directory isn't writable. Claude Code shows a one-time startup notice when it can't auto-update for this reason, and claude doctor lists the fixes. Resist the urge to reach for sudo, which converts a small problem into a permissions mess.

Alpine and other musl distributions. Alpine ships without bash or curl, so the documented install command fails with a not found error until you add them. Install the runtime dependencies, then turn off the bundled ripgrep:

apk add bash curl libgcc libstdc++ ripgrep

Then set USE_BUILTIN_RIPGREP to "0" in the env key of your settings.json. If apk reports ripgrep is missing, it lives in the community repository, which you may need to add first.

Root or sudo refusal. On Linux and macOS, Claude Code refuses to start with --dangerously-skip-permissions while running as root, printing --dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons. The check is skipped inside a recognized sandbox. To run autonomously in a container, use the dev container configuration, which runs Claude Code as a non-root user.

Beyond that, verifying what you installed is a two-minute job worth doing on a work machine. Every release publishes a manifest.json of SHA256 checksums signed with Anthropic's GPG key, so verifying the signature on the manifest transitively verifies every binary it lists. macOS binaries are additionally signed by "Anthropic PBC" and notarized; Windows binaries are signed by "Anthropic, PBC."

A Clean Install Is a Four-Line Checklist

You don't need to remember any of this beyond four checks. Run the native installer for your platform. Run claude --version and confirm the number matches what you just installed. Run claude doctor and read what it says instead of skimming it. Then run claude in a real project and log in. If all four pass, your install is genuinely fine, and any weirdness after that belongs to your configuration rather than your binary. If any one of them fails, the failing check names the problem, which is the whole reason to run them in that order rather than debugging a live session at 11pm.

Browse next: Claude Code Pricing (2026) | Claude Code Permissions (2026) | How to Add Skills to Claude Code | Claude Code Plan Mode (2026)

Back to Blog