Advanced setup

The quickstart gets you to a first session in two minutes. This page is the long version: what Claude Code needs to run, every supported way of installing it, how updates work and how to control them, how to verify the binary you downloaded, and how to remove it cleanly. Admins packaging Claude Code for a fleet will want most of it.

What you need

Claude Code relies on ripgrep for file search. It normally ships bundled, so you only need to think about it on musl-based distributions (below) or if search starts failing.

You also need an account that includes Claude Code: Pro, Max, Team, Enterprise or a Claude Console account. The free claude.ai plan does not include it. Alternatively you can point Claude Code at Amazon Bedrock, Google Vertex AI or Microsoft Foundry.

Tip: If you would rather not use a terminal at all, the desktop app runs Claude Code sessions in a graphical window.

Install

Native installer (recommended)

The native installer drops a self-contained binary into your home directory and keeps it up to date in the background.

# macOS, Linux, 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

The script prints nothing while it downloads, so give it a moment. Then open a new terminal and run claude --version. If the shell says claude is not found, the install directory is not on your PATH yet; troubleshooting installation covers the fix.

Two Windows mix-ups catch people regularly. The token '&&' is not a valid statement separator means you pasted the CMD line into PowerShell. 'irm' is not recognized means the reverse. A PowerShell prompt starts with PS.

Homebrew

brew install --cask claude-code

There are two casks. claude-code follows the stable channel (roughly a week behind, skipping releases with serious regressions). claude-code@latest gets each release as it ships. Homebrew installs do not update themselves, so run brew upgrade claude-code (or claude-code@latest) yourself, and brew cleanup now and then because Homebrew keeps old versions.

WinGet

winget install Anthropic.ClaudeCode

Upgrade with winget upgrade Anthropic.ClaudeCode. As with Homebrew, nothing happens automatically.

Linux package managers

Anthropic publishes signed apt, dnf and apk repositories, each with a stable and a latest channel. Updates arrive through your normal system upgrades rather than through Claude Code. All three are signed with the same release key, whose fingerprint is:

31DD DE24 DDFA B679 F42D  7BD2 BAA9 29FF 1A7E CACE

Debian and Ubuntu (apt). Install curl and gnupg first if a minimal image lacks them. Then fetch the key, check it, add the source and install:

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   # compare the fingerprint above

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

For the latest channel, both the path and the suite change: .../apt/latest latest main. If apt update complains about NO_PUBKEY BAA929FF1A7ECACE, the key download failed. Upgrade later with sudo apt update && sudo apt upgrade claude-code.

Fedora and RHEL (dnf). Create /etc/yum.repos.d/claude-code.repo with a [claude-code] section whose baseurl is https://downloads.claude.ai/claude-code/rpm/stable (or /rpm/latest), with gpgcheck=1 and gpgkey=https://downloads.claude.ai/keys/claude-code.asc. Then sudo dnf install claude-code. dnf asks you to accept the key on first install; check the fingerprint before you say yes. Upgrade with sudo dnf upgrade claude-code.

Alpine (apk). Save the RSA key to /etc/apk/keys/claude-code.rsa.pub from https://downloads.claude.ai/keys/claude-code.rsa.pub, append https://downloads.claude.ai/claude-code/apk/stable (or /apk/latest) to /etc/apk/repositories, then apk add claude-code. The key's SHA-256 should be 395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6. Upgrade with apk update && apk upgrade claude-code.

npm

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

The npm package needs Node.js 22 or newer, although older versions only trigger an EBADENGINE warning, because what actually gets installed is the same native binary via a per-platform optional dependency (for example @anthropic-ai/claude-code-linux-x64). Node is not used at runtime. Supported platforms are darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 and win32-arm64, and your package manager must allow optional dependencies.

To upgrade, use npm install -g @anthropic-ai/claude-code@latest; npm update -g can get stuck inside the original semver range.

Warning: Never use sudo npm install -g. If you hit permission errors, fix your npm prefix instead.

Installing a particular version or channel

The native installer takes an optional argument: stable, latest or an exact version. Whatever you choose becomes the default channel for future auto-updates.

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

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

In CMD, put the argument after install.cmd, for example install.cmd 2.1.89.

Windows: native or WSL?

On native Windows you do not need Administrator rights. Git for Windows is optional but worth having: it provides Git Bash, which the Bash and Monitor tools use. Without it, Claude Code runs shell commands through its PowerShell tool. If Git Bash is installed somewhere unusual, tell Claude Code where:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "D:\\Tools\\Git\\bin\\bash.exe"
  }
}

With Git for Windows present, the PowerShell tool sits alongside Bash. It is on by default for claude.ai and Console accounts; on Bedrock, Vertex AI and Foundry set CLAUDE_CODE_USE_POWERSHELL_TOOL=1 to enable it (or 0 to turn it off anywhere).

For WSL, open the distribution and run the Linux installer inside it. Install and launch from the WSL shell, not from PowerShell.

Alpine and other musl systems

Alpine lacks bash and curl out of the box, so the install script fails with not found until you add them. At runtime you also need libgcc, libstdc++ and a system ripgrep:

apk add bash curl libgcc libstdc++ ripgrep

ripgrep lives in Alpine's community repository; add it to /etc/apk/repositories and apk update if apk cannot find the package. Then tell Claude Code to use the system ripgrep:

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

Check the install

claude --version should print something like 2.1.211 (Claude Code). For a fuller health check, run:

claude doctor

This prints install health, settings validation errors, the result of the last update attempt and suggested fixes, all without starting a session.

To sign in, run claude and follow the browser prompts. If ANTHROPIC_API_KEY is set and you approve its use when asked, the login step is skipped. Authentication covers every option.

Updates

How auto-update works

Native installs check for updates at startup and periodically while running, download in the background and switch over the next time you launch. On macOS and Linux the launcher at ~/.local/bin/claude is a symlink into ~/.local/share/claude/versions/.

If you replace that launcher with your own script, updates leave it alone (from v2.1.207 onwards) and install new versions next to it; your script decides which runs. Claude Code then keeps every version on disk because it cannot tell which one you need. Delete your launcher and run claude update to hand control back.

Homebrew, WinGet, apt, dnf and apk installs do not auto-update. For Homebrew and WinGet you can opt in by setting CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1, and Claude Code runs the upgrade for its own package in the background, then prompts you to restart. WinGet upgrades can fail while Claude Code is running because Windows locks the executable; you will be shown the manual command. The Linux package managers always need a manual, elevated upgrade. Occasionally you will be told about a new version before the package manager has it; just try again later.

Release channels

The autoUpdatesChannel setting picks the channel for auto-updates and claude update:

• "latest" (default): every release as soon as it ships.
• "stable": a build about a week old that skipped any release with major regressions.

Change it in /config under Auto-update channel, or in settings. Homebrew picks the channel by cask name and the Linux repositories by URL, so this setting does not apply there. One catch: a brand-new model can need a version newer than stable has, in which case move to latest.

Version floors and ranges

minimumVersion stops updates from installing anything older. It is useful when you move from latest to stable but do not want to roll back. Switching to stable in /config asks whether to stay put; choosing to stay sets minimumVersion for you, and switching back to latest clears it.

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

That only constrains updates. To refuse to start outside a range, admins use the managed keys requiredMinimumVersion and requiredMaximumVersion; updates also respect that ceiling. See managed settings.

Turning updates off

Put either under env in a settings file.

Updating by hand

claude update installs the newest version immediately and reports Successfully updated from X to version Y, or Claude Code is up to date (X) if there is nothing new.

Network home directories

A running session reads pieces of its executable from disk throughout, not only at launch. If the file vanishes mid-session (common on NFS homes shared between machines), the session dies, often with Bus error on Linux. If your homes are on shared storage:

• Install the binary on local disk, for instance via a Linux package.
• Give each version its own directory and move users across, rather than upgrading in place.
• Only delete an old version once you are sure no machine can still be running it. You cannot see processes on other hosts.
• Set DISABLE_UPDATES and roll out with your own tooling. DISABLE_AUTOUPDATER is not enough, because users can still run claude update.

Be aware that the native installer prunes ~/.local/share/claude/versions/ itself: it keeps the launcher's target, anything running on the same machine and the two newest versions, and deletes the rest.

Verifying the binary

Every release (from 2.1.89) publishes a manifest.json of SHA-256 checksums and a detached GPG signature. Verify the signature once and you have verified every binary it lists.

curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import
gpg --fingerprint security@anthropic.com      # must match the fingerprint above

BASE=https://downloads.claude.ai/claude-code-releases
REL=2.1.200
curl -fsSLO "$BASE/$REL/manifest.json"
curl -fsSLO "$BASE/$REL/manifest.json.sig"
gpg --verify manifest.json.sig manifest.json

Look for Good signature from "Anthropic Claude Code Release Signing <security@anthropic.com>". The "key is not certified" warning is normal for a freshly imported key. Then hash the binary (sha256sum, shasum -a 256, or Get-FileHash ... -Algorithm SHA256 in PowerShell) and compare with platforms.<platform>.checksum in the manifest. An installed native binary lives at ~/.local/share/claude/versions/<version>.

Platform signatures add another layer: macOS binaries are signed by "Anthropic PBC" and notarised (check with codesign --verify --verbose), Windows binaries are signed by "Anthropic, PBC" (check with Get-AuthenticodeSignature). Linux binaries are not individually signed, so rely on the manifest or on the package manager's repository signature.

Uninstalling

If claude still runs afterwards, there is a second install or an old shell alias somewhere.

To wipe configuration too, delete ~/.claude and ~/.claude.json, plus any project-level .claude/ folders and .mcp.json files. This removes settings, permissions, MCP configuration and session history for good. The VS Code extension, JetBrains plugin and desktop app also write to ~/.claude/, so uninstall those first or the folder will reappear.

Related

• Quickstart
• Troubleshooting installation
• Authentication
• Managed settings
• Network configuration