← All posts

Guide

How to install Claude Code (macOS, Windows, Linux & WSL)

The current, recommended way to install Claude Code is the native installer, not npm. On macOS, Linux or WSL run curl -fsSL https://claude.ai/install.sh | bash. In Windows PowerShell run irm https://claude.ai/install.ps1 | iex. It downloads a self-contained binary — no Node.js involved — and keeps itself updated in the background. Then run claude --version to confirm, and claude inside a project to sign in and start. The npm package still works but Anthropic now labels it deprecated. Everything below is the long version: every install route, how to verify it, and the errors that actually stop people.

Before you start: prerequisites and version checks

Three boxes to tick. Two of them are usually already ticked.

• A supported OS. Anthropic publishes these as hard requirements: macOS 13.0 or newer; Windows 10 build 1809+ or Windows Server 2019+; Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+. Hardware: 4 GB+ RAM, and a 64-bit CPU (x64 or ARM64) — 32-bit is not supported. Bash, Zsh, PowerShell and CMD are all fine. You need an internet connection and to be in a country Anthropic supports.
• Node.js — only if you choose the npm route. The native installer, Homebrew and WinGet all deliver a self-contained binary that does not need Node at all, so most people can skip this. If you insist on npm, check with node --version: as of v2.1.198 the package declares Node.js 22 or later. If you read "Node 18+" anywhere — including the badge on the GitHub README — that is stale.
• A paid Anthropic account. Claude Code requires a Pro, Max, Team, Enterprise or Console account. The free Claude.ai plan does not include access. Alternatively you can route through Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a self-hosted Claude apps gateway.

Pick an install route

There are five real routes and they differ mainly in who owns updates. If you have no preference, take the native installer — it is the one Anthropic recommends and the only one that updates itself.

Install on macOS

The native installer, run from Terminal or iTerm2:

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

That places the binary at ~/.local/bin/claude (a symlink into ~/.local/share/claude/versions/) and wires up background updates. If you would rather your package manager owned it, Homebrew has an official cask:

brew install --cask claude-code

There are two casks and the difference matters. claude-code follows the stable channel, which trails latest by roughly a week and skips releases with major regressions; claude-code@latest follows latest. Homebrew installs do not auto-update — run brew upgrade claude-code yourself. If brew reports Cask 'claude-code' is unavailable, run brew update and retry. Casks are a macOS mechanism, so treat this as the macOS route only.

Install on Windows

In PowerShell (not CMD):

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

In Command Prompt:

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

Or through WinGet, if you standardise on it:

winget install Anthropic.ClaudeCode

WinGet installs do not auto-update either — refresh with winget upgrade Anthropic.ClaudeCode. For both Homebrew and WinGet you can opt in to having Claude Code run that upgrade for you by setting CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1, though on WinGet it can fail while Claude Code is running because Windows locks the executable.

Native Windows is fully supported, and Git for Windows is optional: with it installed, Claude Code uses Git Bash for its Bash tool; without it, it falls back to the PowerShell tool. If your Git lives somewhere non-standard, point at it with CLAUDE_CODE_GIT_BASH_PATH in the env block of your settings.json. We go deeper on the platform in running Claude Code on Windows.

WSL is a choice, not a fallback

Older tutorials treat WSL as the workaround for Windows. That framing is out of date — but WSL 2 still wins on one concrete axis. Anthropic's own matrix: native Windows requires nothing extra but does not support sandboxing; WSL 2 does support sandboxed command execution and is the right pick for Linux toolchains; WSL 1 supports neither and is only worth it if WSL 2 is unavailable.

Inside WSL you run the Linux installer from the WSL terminal, not from PowerShell, and you do not need Git for Windows. Two known WSL failures: on WSL 1 you may see cannot execute binary file: Exec format error, fixed by wsl --set-version <DistroName> 2; and, if you installed through npm inside WSL, exec: node: not found, which means WSL picked up the Windows Node. Check with which node and which npm — a path starting /mnt/c/ is a Windows binary — then install Node through your Linux distribution's package manager or nvm.

The npm route (still works, no longer recommended)

Anthropic's README now carries a note reading "Installation via npm is deprecated" and lists the command under a heading of NPM (Deprecated). No removal date has been announced and the docs still cover it under advanced options — it is simply not the path to pick for a fresh install.

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

Two things to know. First, never use sudo npm install -g — the docs warn against it explicitly for both permission and security reasons. Second, upgrade with npm install -g @anthropic-ai/claude-code@latest, not npm update -g, which respects the original semver range and will quietly leave you behind. On Node older than 22 npm prints an EBADENGINE warning; the install usually still completes and claude still runs, because the package pulls down a native binary that does not use your Node at runtime.

Verify it worked

Three checks, in escalating order.

claude --version

A healthy install prints a version number followed by (Claude Code) — for example 2.1.220 (Claude Code). If that works, you are installed.

claude doctor

Run from your shell, this prints read-only installation and settings diagnostics without starting a session: install health, settings-file validation errors, warnings with suggested fixes, and the result of the most recent update attempt. It is the fallback when claude will not start at all.

Inside a running session, /doctor does more: it runs the same setup checkup and can apply the fixes rather than only listing them. See the slash command reference for the rest of the in-session commands.

Sign in

Launch it for the first time by just typing:

claude

On first run it walks you through browser OAuth. Type /login if it does not prompt automatically. The decision that matters: a Claude subscription (Pro, Max, Team or Enterprise) bundles Claude Code into your flat fee, while an Anthropic Console login bills per token against API credits — on first Console login a "Claude Code" workspace is created automatically for cost tracking. You can switch later. Credentials land in the macOS Keychain, or in ~/.claude/.credentials.json (mode 0600) on Linux, or %USERPROFILE%\.claude\.credentials.json on Windows. For CI, mint a one-year token with claude setup-token and set it as CLAUDE_CODE_OAUTH_TOKEN.

Your first run

Change into a project you don't mind it touching, start it, and give it something small:

cd my-project
claude

Then describe a task in plain English — "add a health-check endpoint and a test for it," say. Claude Code will propose edits and commands; by default it asks before running anything that changes files or executes shell commands, so you approve each step the first few times until you trust it. Start in a git repo with a clean working tree so you can always git diff what it did and roll back if needed.

Troubleshooting the errors that actually happen

"command not found: claude"

This is a PATH problem in nearly every case, and the most common cause is boring: the terminal you installed from is still holding its old PATH. Open a new terminal window before concluding anything failed. The error text varies by shell — zsh: command not found: claude on macOS, bash: claude: command not found on Linux, 'claude' is not recognized as an internal or external command in CMD, claude : The term 'claude' is not recognized as the name of a cmdlet in PowerShell — but the fix is the same. Check whether the install directory is on your PATH:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

If it prints nothing, add it. For Zsh (the macOS default):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Bash users put the same line in ~/.bashrc. On Windows, check with $env:PATH -split ';' | Select-String '\.local\\bin', then read the user PATH with [Environment]::GetEnvironmentVariable('PATH','User'), append %USERPROFILE%\.local\bin to it via [Environment]::SetEnvironmentVariable('PATH', ..., 'User'), and restart the terminal.

Permission and EACCES errors

Anthropic's first-line answer to npm EACCES errors is now "stop using npm" — switch to curl -fsSL https://claude.ai/install.sh | bash. If you are staying on npm, npm's own guidance gives two fixes: reinstall Node through a version manager like nvm (npm calls this the best way to avoid permission issues), or change npm's default directory with npm config set prefix ~/.local plus PATH=~/.local/bin:$PATH in ~/.profile — conveniently the same place the native installer writes. If the native install hits a permission failure, check with test -w ~/.local/bin and repair with sudo mkdir -p ~/.local/bin and sudo chown -R $(whoami) ~/.local. If an npm global install cannot auto-update because the global directory is not writable, Claude Code shows a one-time startup notice and claude doctor lists the fixes.

You pasted the command into the wrong Windows shell

Each error names the mistake. 'irm' is not recognized means you are in CMD running the PowerShell command; The token '&&' is not a valid statement separator means the reverse; A parameter cannot be found that matches parameter name 'fsSL' or 'bash' is not recognized means you pasted the macOS/Linux command into PowerShell. Your prompt tells you which you are in — PS C:\ is PowerShell, plain C:\ is CMD. Two more: running scripts is disabled on this system hits npm installs only, because npm ships PowerShell shims — fix with Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser, call claude.cmd, or use the PowerShell installer, which lays down a binary rather than a script. And Claude Code does not support 32-bit Windows usually means you opened "Windows PowerShell (x86)" — confirm with [Environment]::Is64BitOperatingSystem and reopen the non-x86 entry. An old Claude Desktop can also register a Claude.exe in WindowsApps that shadows the CLI; updating Desktop clears it.

Corporate proxy and TLS inspection

Export the proxy before running the installer — export HTTP_PROXY=http://proxy.example.com:8080 and the matching HTTPS_PROXY (PowerShell: $env:HTTPS_PROXY = 'http://proxy.example.com:8080'). Test with curl -sI https://downloads.claude.ai/claude-code-releases/latest: HTTP/2 200 means you reached the server, 403 usually means a proxy, a content filter or an unsupported country, 5xx is transient. In PowerShell type curl.exe — PowerShell aliases curl to Invoke-WebRequest. A TLS-inspecting proxy gives you unable to get local issuer certificate or SELF_SIGNED_CERT_IN_CHAIN: install with curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash and set NODE_EXTRA_CA_CERTS to the same file for runtime. SOCKS proxies are not supported. Minimum firewall allowlist: api.anthropic.com, claude.ai, claude.com, platform.claude.com, downloads.claude.ai, plus registry.npmjs.org for npm.

The install is "Killed" on a small Linux box

Installing needs roughly 512 MB of free memory. On a cheap VPS the Linux OOM killer ends it with Killed and exit code 137. Add swap and retry:

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

Sign-in fails

Generic reset first: /logout, close Claude Code, restart with claude. If the browser never opens, press c at the login prompt to copy the OAuth URL and paste it into a browser by hand. In WSL 2, SSH sessions and containers the browser opens on a different host and the callback cannot reach your local server, so you get a login code instead — paste it at the Paste code here if prompted prompt, or, if pasting into the interactive prompt does nothing, run claude auth login, which reads the code from stdin. From WSL 2 you can also set BROWSER to your Windows Chrome path under /mnt/c/.

Specific errors map to specific causes. OAuth error: Invalid code means the code expired or got truncated — retry and finish quickly. A 403 forbidden / Request not allowed straight after login means the subscription is not active, or (on Console) your account lacks the "Claude Code" or "Developer" role. 400 ... This organization has been disabled while your subscription is plainly fine is the sneaky one: a stale ANTHROPIC_API_KEY is overriding your subscription. Run unset ANTHROPIC_API_KEY and strip the export from ~/.zshrc, ~/.bashrc or ~/.profile (on Windows, your $PROFILE and user environment variables). /status tells you which credential is actually in play. On macOS a locked Keychain also blocks login — unlock it with security unlock-keychain ~/Library/Keychains/login.keychain-db.

Once you are in and running real tasks, the next wall is usually quota rather than install; our notes on Claude Code usage limits cover how the weekly and session ceilings behave.

Updating, and picking a release channel

Native installs update themselves. There are two channels you can choose between: latest (the default) and stable, which runs about a week behind. Set it via /config → Auto-update channel, or autoUpdatesChannel in settings.json. The installer accepts the same argument, and a pinned version too:

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

Windows PowerShell needs the argument wrapped rather than appended: & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable.

To force an update or repair a broken binary in place, claude update or claude install [version] (which also accepts stable or latest). For reference, on July 30, 2026 the latest tag resolved to 2.1.220 and stable to 2.1.212 — expect both to have moved by the time you read this.

Uninstall and reinstall

Remove the binary the same way you installed it:

• Native (macOS/Linux/WSL): rm -f ~/.local/bin/claude and rm -rf ~/.local/share/claude
• Native (Windows): delete %USERPROFILE%\.local\bin\claude.exe and the %USERPROFILE%\.local\share\claude folder
• Homebrew: brew uninstall --cask claude-code (or claude-code@latest, whichever cask you installed)
• WinGet: winget uninstall Anthropic.ClaudeCode
• npm: npm uninstall -g @anthropic-ai/claude-code

That leaves your configuration alone. To wipe that too — settings, allowed tools, MCP config and session history, so treat it as destructive — remove ~/.claude and ~/.claude.json, plus per-project .claude and .mcp.json. If claude still runs after you uninstalled it, you have a second install. Find it with which -a claude (where.exe claude on Windows) and check the three usual suspects: ~/.local/bin/claude (native), ~/.claude/local/ (a legacy local npm install from older versions), and npm -g ls @anthropic-ai/claude-code.

What to do next

Give the agent project context before you give it work — a CLAUDE.md at the repo root is the highest-leverage twenty minutes you will spend, and our CLAUDE.md generator gets you a first draft. After that, hooks let you fire your own scripts on tool use and completion, and slash commands shorten the loops you repeat. If you also use Cursor, its terminal agent installs in about two minutes — here's how to install the Cursor CLI (cursor-agent). And if you would rather skip the terminal entirely, Anthropic's docs point at a GUI desktop app as an alternative front end.

Keep the agent where you can see it

Here's the thing nobody warns you about: once Claude Code is doing real work, a single task can run for minutes, and it stops mid-way to ask permission or finishes while you've tabbed away to your editor or a browser. The terminal ends up buried, and the agent sits idle waiting on you. There are a few ways to handle that — from running it in the background to wiring up notifications so you stop babysitting it.

Frequently asked questions

Where Backgrind fits

Backgrind is not a model and not an agent. It is a desktop overlay for macOS and Windows that PTY-wraps the claude CLI you just installed — your login, your history, your config — in an always-on-top window that floats over whatever else is on screen, including borderless-fullscreen games, and pings you only when the agent needs a decision or finishes. In BYO-CLI mode your agent's content never touches our servers; Live mode (Plus and Pro) lets you answer those prompts from a phone or browser. It wraps Cursor, Codex and OpenCode the same way, or you can run a managed endpoint (Grindy). The install you just did is all you need to work from the terminal today — Backgrind is about what happens after.

Sources

Install commands, system requirements, release channels and uninstall steps: Claude Code — set up. First run and login flow: quickstart. PATH, permission, proxy, low-memory and WSL errors: troubleshoot installation and troubleshooting. Credential storage, login codes and CI tokens: authentication. The auto-created Console “Claude Code” workspace: manage costs. Proxy variables, TLS certificates and the firewall allowlist: network configuration. claude update, claude install and setup-token: CLI reference. The npm deprecation note: anthropics/claude-code README. Version numbers and cask names were read live on July 30, 2026 from the npm registry, the Homebrew cask API and downloads.claude.ai. npm's own permission guidance: resolving EACCES permissions errors.