Install Claude Code on macOS, Linux, and Windows

Claude Code installs as a single native binary through Anthropic’s native installer, Homebrew, WinGet, signed apt/dnf/apk repositories, or npm (Node.js 22+). The native installer and npm auto-update; package-manager installs do not by default. Every method except WinGet offers a latest and a stable release channel, and claude doctor confirms the install, update status, and settings health.

This page is for the developer putting Claude Code on a work machine and for the tech lead who has to make that install identical across a team. The usual mess: one person installed through npm a year ago, another through Homebrew, a third has two claude binaries on PATH, and nobody can say which version is running or why a feature from the changelog is missing. A few minutes of deliberate setup here prevents that.

What a verified Claude Code install gives you

• One claude binary on your PATH, installed by a method you chose on purpose.
• A release channel (latest or stable) you picked, and an update policy that matches it.
• A clean claude doctor report you can keep as evidence that the install is healthy.
• A read-only smoke test whose answer you check against your repository in under a minute.
• A setup-check script a tech lead can hand to every new team member.

Which Claude Code install method should you choose?

Use the native installer unless something rules it out. It needs no Node.js, installs without administrator rights, and keeps itself current without extra configuration.

Method	Platforms	Updates	Channel	Choose it when
Native installer	macOS, Linux, WSL, Windows	Automatic, in the background	latest by default; stable on request	Almost always
Homebrew	macOS	Manual (brew upgrade), or opt in	Cask claude-code = stable, claude-code@latest = latest	Your team manages every tool through Homebrew
WinGet	Windows	Manual (winget upgrade), or opt in	—	Windows fleet managed through WinGet
apt / dnf / apk	Debian, Ubuntu, Fedora, RHEL, Alpine	Through your normal system upgrades	stable or latest repository	Servers and images where every binary must come from a signed package repository
npm	Any platform with Node.js 22+	Background, if the npm global directory is writable	npm dist-tags latest and stable	You already standardise global tools on npm

The npm package installs the same native binary as the other methods; the installed claude does not run on your Node.js. If you prefer a graphical client, the Claude Code desktop app runs without a terminal, but install the CLI anyway: the diagnostics on this page live there.

Which release channel should you follow?

The latest channel ships every release as soon as it is published, roughly one a day. The stable channel is typically about a week behind and skips releases with major regressions. On 2026-09-26, latest was v2.1.283 and stable was v2.1.274 (npm dist-tags, checked that day).

The gap matters for more than bug fixes. Features and model defaults arrive on latest first: the Claude Opus 5.5 default needs v2.1.280, so a stable install on 2026-09-26 still ran the older defaults. The models hub keeps the current table. Pick latest on your own machine if you want new features the day they ship; pick stable for a team that values fewer surprises over speed.

Check the Claude Code system requirements

Requirement	Supported
Operating system	macOS 13.0+, Windows 10 1809+ or Windows Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
Hardware	4 GB+ RAM, x64 or ARM64 processor (32-bit Windows is not supported)
Shell	Bash, Zsh, PowerShell, or CMD
Network	Internet access to Anthropic’s download and API hosts
Location	An Anthropic-supported country
Account	Pro, Max, Team, Enterprise, or Console account, or a cloud provider; the free Claude plan does not include Claude Code

The installer itself needs roughly 512 MB of free memory, which small cloud instances sometimes lack (see the failure modes below).

Install Claude Code

Run the native installer and npm commands in a regular terminal, not as root and not with sudo; the system-package commands below need elevated privileges.

Native (recommended)

macOS, Linux, and WSL:

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

Windows PowerShell (your prompt starts with PS C:\):

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

Windows CMD (your prompt starts with C:\ and no PS):

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

To install the stable channel instead, pass it to the script. The channel you install with becomes your auto-update channel:

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

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

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

On macOS and Linux the installer puts a launcher at ~/.local/bin/claude that links into ~/.local/share/claude/versions/.

Homebrew

brew install --cask claude-code          # stable channel
# or
brew install --cask claude-code@latest   # latest channel

Homebrew installs do not auto-update. Run brew upgrade claude-code (or claude-code@latest), or set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 so Claude Code runs the upgrade in the background and asks you to restart. Run brew cleanup now and then: Homebrew keeps old versions on disk.

WinGet

winget install Anthropic.ClaudeCode

WinGet installs do not auto-update. Run winget upgrade Anthropic.ClaudeCode, or set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1. Windows locks the running executable, so an automatic upgrade can fail while Claude Code is open; Claude Code then shows the manual command.

apt / dnf / apk

Anthropic signs all three repositories with the Claude Code release key. Verify the key before you trust it. The commands below use the stable channel; replace stable with latest in the URL (and, for apt, in the suite name) to follow latest.

Debian and Ubuntu (apt):

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
# Expect fingerprint 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE
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

Fedora and RHEL (dnf):

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

dnf asks you to confirm the key: accept only 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE.

Alpine (apk, as root):

wget -O /etc/apk/keys/claude-code.rsa.pub https://downloads.claude.ai/keys/claude-code.rsa.pub
sha256sum /etc/apk/keys/claude-code.rsa.pub
# Expect 395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

These installs update only through your system upgrades (sudo apt update && sudo apt upgrade claude-code, sudo dnf upgrade claude-code, apk update && apk upgrade claude-code), because those commands need elevated privileges.

npm

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

The package requires Node.js 22 or later; an older Node prints an EBADENGINE warning but the install still completes. The native binary arrives as a per-platform optional dependency, so your package manager must allow optional dependencies. Upgrade with npm install -g @anthropic-ai/claude-code@latest, not npm update -g, which stays inside the original semver range. Never use sudo npm install -g.

Set up Claude Code on native Windows or WSL

Claude Code runs natively on Windows or inside WSL. Choose by where your code and toolchain live:

Option	Requires	Sandboxing	Use it for
Native Windows	Nothing; Git for Windows optional	Not supported	Windows-native projects and tools
WSL 2	WSL 2 enabled	Supported	Linux toolchains, sandboxed command execution
WSL 1	WSL 1 enabled	Not supported	Only when WSL 2 is unavailable

On native Windows, Claude Code uses Git Bash for its Bash tool when Git for Windows is installed, and the PowerShell tool otherwise. If Git Bash is installed somewhere unusual, set CLAUDE_CODE_GIT_BASH_PATH in the env block of your settings.json. In WSL, install and run claude inside the WSL terminal, not from PowerShell.

Install Claude Code on Alpine and other musl distributions

With the native installer, Alpine needs bash and curl for the install command and libgcc, libstdc++, and ripgrep at runtime. Install them, then tell Claude Code to use the system ripgrep:

apk add bash curl libgcc libstdc++ ripgrep

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

ripgrep lives in Alpine’s community repository; enable it in /etc/apk/repositories if apk cannot find the package.

Prove the Claude Code install works

Do not stop at “the command ran”. Four checks tell you the binary, the environment, and the account all work, and none of them needs you to read code.

1. Open a new terminal and print the version. The terminal you installed from still has the old PATH.

   claude --version

   A working install prints something like 2.1.283 (Claude Code).

2. Check for a second binary. Two installs are a frequent cause of “the update didn’t take”.

   which -a claude        # macOS, Linux, WSL
   where.exe claude       # Windows

   Exactly one path should print.

3. Run the read-only health check. claude doctor reports install health, the auto-update status, settings-file validation errors, and warnings with suggested fixes, without starting a session.

   claude doctor

   Keep this output when you onboard a teammate: it is the evidence that the setup is correct. For a full checkup that can also fix issues, run /doctor inside a session.

4. Sign in and run a smoke test. Start claude in a project directory and follow the browser login; Claude Code authentication covers every account type. Then confirm the login and run a headless, read-only question whose answer you can check yourself:

   claude auth status --text
   claude -p "Which command runs this project's tests? Cite the file and line you read it from." --tools "Read,Glob,Grep"

   --tools "Read,Glob,Grep" limits the session to read-only tools, so the smoke test cannot change anything. --tools takes a list of values, so put it after the prompt or write --tools=Read,Glob,Grep; placed before the prompt, it swallows the prompt as a tool name and the command fails with Input must be provided either through stdin or as a prompt argument (checked on v2.1.283). Open the cited file: if the command is there, the install, the login, and the model connection all work.

Copy-paste prompt: audit this Claude Code install

Audit my Claude Code installation. Do not edit any file or setting.
Run `claude --version`, `which -a claude` (or `where.exe claude` on Windows) and `claude doctor`.
Report in a short table:
1. The installed version.
2. The install method: native launcher in ~/.local/bin, Homebrew, WinGet, npm, or a system package.
3. Whether more than one `claude` binary is on PATH, with every path.
4. The auto-update status and release channel.
5. Every warning `claude doctor` printed, with the fix it suggests.
Finish with one line: INSTALL OK or INSTALL NEEDS ACTION, and the single command I should run next.

Check the answer against your own claude doctor output. If the two disagree, trust the command, not the summary.

Copy-paste prompt: first read-only session in a new repository

Without editing anything, read this repository and tell me:
the main language and framework, the command that installs dependencies,
the command that runs the tests, and the command that runs the linter or type checker.
For each answer, cite the file and line you took it from. If you cannot find one, say so instead of guessing.

Every answer is checkable in seconds by opening the cited file. A confident answer with no citation is the first sign that the agent is guessing, which is worth knowing before you hand it real work.

Control Claude Code updates and release channels

For a native install, set the channel in ~/.claude/settings.json (or through /config → Auto-update channel):

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

minimumVersion is a floor: background updates and claude update never install anything older, so switching from latest to stable does not downgrade you.

You want to	Do this
Update now	claude update
Reinstall a channel or a pinned version	claude install stable, claude install latest, or claude install 2.1.274 (add --force to reinstall)
Stop background update checks	Set "DISABLE_AUTOUPDATER": "1" in the env block of settings.json; claude update still works
Block every update path	Set "DISABLE_UPDATES": "1" in the env block of settings.json (or managed settings), for machines that must stay on a version you distribute; claude update and claude install are blocked too

After you change the update policy, run claude doctor again. With DISABLE_AUTOUPDATER set, its Auto-updates line reads disabled (set by env: DISABLE_AUTOUPDATER).

Make the Claude Code install repeatable for a team

For a tech lead, the goal is that every machine runs a known version from a known source, and that you can prove it without visiting each desk.

• Pick one method and one channel for the team and write them in your onboarding doc. Mixed methods produce the duplicate-binary failures below.
• Enforce the channel and a version range with managed settings. Managed settings can set autoUpdatesChannel, minimumVersion, and the start-up gates requiredMinimumVersion and requiredMaximumVersion, which user and project settings cannot override. Enterprise integration and managed policy for coding agents show the rollout.
• Verify the binary when policy demands it. Each release publishes a manifest.json with SHA-256 checksums, signed with Anthropic’s release key (key fingerprint as above). macOS binaries are signed and notarised, and Windows binaries are signed. Linux binaries are not individually code-signed (setup docs, checked 2026-09-26); on Linux, verify the manifest signature or install from the signed apt/dnf/apk repositories.
• Containers and proxies. For images, set a working directory before the installer runs (see the failure modes below) and consider a devcontainer. Behind a corporate proxy, configure it first with proxy configuration.

Copy-paste prompt: team setup-check script

Write scripts/check-claude-setup.sh, a POSIX shell script every new team member runs after installing Claude Code.
It must:
- fail if `claude` is missing, or if `which -a claude` prints more than one path;
- fail if `claude --version` is below 2.1.274 (compare versions numerically, not as strings);
- run `claude doctor` and fail if it exits non-zero or if its summary line reports one or more warnings or errors (for example `3 warnings found`); do not match the word "error" anywhere else in its output;
- run `claude auth status --text` and fail if the user is not logged in, without printing any token or key;
- print one PASS or FAIL line per check and exit non-zero on any failure.
Do not install or update anything. Then run the script once and show me its output.

On v2.1.283, claude doctor exits with code 0 even when it lists warnings, so the script has to read the summary line rather than rely on the exit code alone. Review the script’s checks, not its every line: run it on one healthy machine (all PASS) and on one where you deliberately put a second claude on PATH (it must FAIL). A check that cannot fail is not a check.

When Claude Code installation breaks

command not found: claude or 'claude' is not recognized. Open a new terminal first. If it still fails, the install directory is not on PATH: check with echo $PATH | tr ':' '\n' | grep -F "$HOME/.local/bin" and add ~/.local/bin to your shell profile. On Windows, add %USERPROFILE%\.local\bin to the user PATH.

The version does not change after an update. You have two installs, and the older one wins on PATH. Run which -a claude, remove every install except the one you want (the uninstall commands are below), and run claude doctor. An old npm install and a native install are the usual pair.

syntax error near unexpected token '<' or a 403 from the install command. The URL returned a web page instead of the script. If the page says “App unavailable in region”, your country is not supported. Otherwise a proxy or a temporary outage is the likely cause: check that you can reach downloads.claude.ai, retry, or use Homebrew or WinGet.

irm is not recognized or The token '&&' is not a valid statement separator. You ran the PowerShell command in CMD, or the CMD command in PowerShell. Check the prompt (PS C:\ is PowerShell) and use the matching command.

Killed or exit code 137 during install on Linux. The out-of-memory killer stopped the installer. Add a 2 GB swap file, close other processes, or use a larger instance, then rerun the installer.

The install hangs in Docker. Installing as root from / makes the installer scan the whole filesystem. Set WORKDIR /tmp before the RUN curl … | bash line.

EACCES on npm install -g. Do not add sudo. Switch to the native installer, or point npm at a user-owned prefix (npm config set prefix ~/.npm-global and add ~/.npm-global/bin to PATH).

Error: claude native binary not installed after npm. Your package manager skipped the optional dependency or its postinstall step. Reinstall with optional dependencies and scripts allowed, or switch to the native installer.

claude update or claude doctor hangs. On versions before v2.1.214, a directory at a shell-config path such as ~/.zshrc caused the hang. Move the directory aside, then rerun the install script, because claude update itself hangs.

If none of these match, the Claude Code troubleshooting guide covers runtime errors after install.

Uninstall Claude Code

Remove the binary with the command for your install method:

# Native (macOS, Linux, WSL)
rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude
# Homebrew
brew uninstall --cask claude-code        # or claude-code@latest
# npm
npm uninstall -g @anthropic-ai/claude-code
# apt: package, repository file and key
sudo apt remove claude-code
sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc
# dnf: package and repository file
sudo dnf remove claude-code
sudo rm /etc/yum.repos.d/claude-code.repo

# apk (as root): package, repository line and key
apk del claude-code
sed -i '\|downloads.claude.ai/claude-code/apk|d' /etc/apk/repositories
rm /etc/apk/keys/claude-code.rsa.pub

# Native (Windows PowerShell)
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

To remove settings, MCP configuration, and session history as well, delete ~/.claude/ and ~/.claude.json, and .claude/ and .mcp.json inside each project. Uninstall the IDE extensions and the desktop app first, or they recreate ~/.claude/ on their next run. If claude still runs afterwards, a second install is left: run which -a claude again.

Where to go next after installing Claude Code

Authenticate Claude Code Subscription, Console, or cloud-provider login, and how to prove it.

Configure Claude Code Permission modes, model selection, and the settings hierarchy.

Connect your IDE VS Code and JetBrains integration on top of the CLI.

Install Codex The sibling guide if your team runs Codex too.

Setting up Cursor instead? See Cursor installation and setup. New to the whole path? The developer track orders the next steps.