| title | Advanced setup |
|---|---|
| source | https://code.claude.com/docs/en/setup |
| category | code |
| generated | true |
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.
System requirements, platform-specific installation, version management, and uninstallation for Claude Code.
This page covers system requirements, platform-specific installation details, updates, and uninstallation. For a guided walkthrough of your first session, see the quickstart. If you've never used a terminal before, see the terminal guide.
Claude Code runs on the following platforms and configurations:
- 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
- Network: internet connection required. See network configuration.
- Shell: Bash, Zsh, PowerShell, or CMD.
- Location: Anthropic supported countries
- ripgrep: usually included with Claude Code. If search fails, see search troubleshooting.
To install Claude Code, open a terminal and run the command for your system. If you haven't used a terminal before, the terminal guide shows how to open one and paste the command.
**macOS, Linux, WSL:**```bash theme={null}
curl -fsSL https://claude.ai/install.sh | bash
```
**Windows PowerShell:**
```powershell theme={null}
irm https://claude.ai/install.ps1 | iex
```
**Windows CMD:**
```batch theme={null}
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](/docs/en/troubleshoot-install#command-not-found-claude-after-installation).
If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell. Your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.
If the install command fails with `syntax error near unexpected token '<'`, a `403`, or another curl error, see [Troubleshoot installation](/docs/en/troubleshoot-install#find-your-error) to match the error to a fix and for alternative install methods.
[Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.
<Info>
Native installations automatically update in the background to keep you on the latest version.
</Info>
Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.
<Info>
Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.
</Info>
<Info>
WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.
</Info>
You can also install with apt, dnf, or apk on Debian, Fedora, RHEL, and Alpine.
After installation completes, open a terminal in the project you want to work in and start Claude Code:
claudeClaude Code opens an interactive session in your terminal.
If you encounter any issues during installation, see Troubleshoot installation and login.
You can run Claude Code natively on Windows or inside WSL. Pick based on where your projects are located and which features you need:
| Option | Requires | Sandboxing | When to use |
|---|---|---|---|
| Native Windows | None; Git for Windows is optional | Not supported | Windows-native projects and tools |
| WSL 2 | WSL 2 enabled | Supported | Linux toolchains or sandboxed command execution |
| WSL 1 | WSL 1 enabled | Not supported | If WSL 2 is unavailable |
Option 1: Native Windows
Run the install command from PowerShell or CMD. You do not need to run as Administrator. Installing Git for Windows is optional. It provides Git Bash, which the Bash tool and the Monitor tool need.
Whether you install from PowerShell or CMD only affects which install command you run. Your prompt shows PS C:\Users\YourName> in PowerShell and C:\Users\YourName> without the PS in CMD. If you're new to the terminal, the terminal guide walks through each step.
After installation, launch claude from any terminal.
-
Without Git for Windows, Claude Code runs shell commands via the PowerShell tool.
-
With Git for Windows, Claude Code uses Git Bash for the Bash tool. If Claude Code can't find Git Bash, set the path in your settings.json file:
{ "env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" } }
When Git for Windows is installed, the PowerShell tool is available alongside Bash: on by default for claude.ai and Console accounts, and enabled with CLAUDE_CODE_USE_POWERSHELL_TOOL=1 in Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry sessions. Set it to 0 to turn the tool off. See PowerShell tool for setup and limitations.
Option 2: WSL
Open your WSL distribution and run the Linux installer from the install instructions above. You install and launch claude inside the WSL terminal, not from PowerShell or CMD.
Installing Claude Code on Alpine and other musl/uClibc-based distributions requires bash and curl for the install command, and libgcc, libstdc++, and ripgrep at runtime. Alpine doesn't include bash or curl by default, so the documented install command fails with a not found error until you install them. Install these packages using your distribution's package manager, then set USE_BUILTIN_RIPGREP=0.
This example installs the required packages on Alpine:
apk add bash curl libgcc libstdc++ ripgrepOn Alpine, ripgrep is in the community repository. If apk reports that the package is missing, add the community repository to /etc/apk/repositories, using your Alpine version:
echo "https://dl-cdn.alpinelinux.org/alpine/v3.22/community" >> /etc/apk/repositoriesRun apk update to refresh the package index, and retry the apk add command.
Then set USE_BUILTIN_RIPGREP to 0 in your settings.json file:
{
"env": {
"USE_BUILTIN_RIPGREP": "0"
}
}After installing, confirm Claude Code is working:
claude --versionA working installation prints a version number such as 2.1.211 (Claude Code).
If this fails with command not found or another error, see Troubleshoot installation and login.
For a more detailed check of your installation and configuration, run claude doctor:
claude doctorclaude doctor prints read-only installation and settings diagnostics without starting a session, including install health, settings-file validation errors, and any warnings with suggested fixes.
Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry.
After installing, log in by running claude and following the browser prompts. If the ANTHROPIC_API_KEY environment variable is set, Claude Code prompts you once to approve the key instead of opening a browser. See Authentication for all account types and team setup options.
Native installations automatically update in the background. You can configure the release channel to control whether you receive updates immediately or on a delayed stable schedule, or disable auto-updates entirely. Homebrew, WinGet, and Linux package manager installations require manual updates by default.
Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code.
Run claude doctor to see the result of the most recent update attempt.
On macOS and Linux, the native installer manages the launcher at ~/.local/bin/claude as a symlink into ~/.local/share/claude/versions/. If you replace that launcher with your own script or symlink, auto-update and claude update leave it in place: new versions still install under the versions/ directory, and your launcher decides which version runs. Before v2.1.207, the auto-updater replaced a custom launcher at that path with its own symlink on every update.
With a custom launcher, Claude Code also keeps every installed version on disk because it can't tell which version the launcher needs. claude doctor reports a launcher that the native installer didn't create.
To let Claude Code manage the launcher again, remove ~/.local/bin/claude and run claude update.
If an npm global install can't auto-update because the npm global directory isn't writable, Claude Code shows a one-time notice at startup, and claude doctor lists the available fixes. See permission errors during installation for details.
To have Claude Code run the upgrade command for you on Homebrew or WinGet, set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1. Claude Code then runs the upgrade in the background when a new version is available and shows a restart prompt on success. The upgrade targets only the Claude Code package and does not affect other software you have installed.
On WinGet the upgrade may fail while Claude Code is running because Windows locks the executable. In that case Claude Code shows the manual command instead. apt, dnf, and apk continue to require a manual upgrade because those commands need elevated privileges.
Known issue: Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.
Homebrew keeps old versions on disk after upgrades. Run brew cleanup periodically to reclaim disk space.
Control which release channel Claude Code follows for auto-updates and claude update with the autoUpdatesChannel setting:
"latest", the default: receive new features as soon as they're released"stable": use a version that is typically about one week old, skipping releases with major regressions
Configure this via /config → Auto-update channel, or add it to your settings.json file:
{
"autoUpdatesChannel": "stable"
}A newly launched model can require a Claude Code version newer than the stable channel serves. To run the model now, move to the latest channel.
For enterprise deployments, you can enforce a consistent release channel across your organization using managed settings.
Homebrew installations choose a channel by cask name instead of this setting: claude-code tracks stable and claude-code@latest tracks latest.
Installations from the apt, dnf, and apk repositories choose a channel by repository instead of this setting. To switch one, follow Install with Linux package managers.
The minimumVersion setting establishes a floor. Background auto-updates and claude update refuse to install any version below this value, so moving to the "stable" channel does not downgrade you if you are already on a newer "latest" build.
Switching from "latest" to "stable" via /config prompts you to either stay on the current version or allow the downgrade. Choosing to stay sets minimumVersion to that version. Switching back to "latest" clears it.
Add it to your settings.json file to pin a floor explicitly:
{
"autoUpdatesChannel": "stable",
"minimumVersion": "2.1.100"
}In managed settings, this enforces an organization-wide minimum that user and project settings cannot override.
The minimumVersion pin only constrains updates. To make Claude Code refuse to start outside a version range, use the managed settings requiredMinimumVersion and requiredMaximumVersion instead. Updates also respect the requiredMaximumVersion ceiling. See requiredMinimumVersion and requiredMaximumVersion.
Set DISABLE_AUTOUPDATER to "1" in the env key of your settings.json file:
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}On a native or npm installation, confirm the change took effect by running claude doctor and checking that the Auto-updates line shows disabled (set by env: DISABLE_AUTOUPDATER) instead of enabled.
DISABLE_AUTOUPDATER only stops the background check; claude update and claude install still work. To block all update paths, including manual updates, set DISABLE_UPDATES instead. Use this when you distribute Claude Code through your own channels and need users to stay on the version you provide.
To apply an update immediately without waiting for the next background check, run:
claude updateWhen an update installs, the command reports Successfully updated from <old version> to version <new version>. If you're already on the newest version, it reports Claude Code is up to date (<version>). Installs managed by Homebrew, WinGet, or apk report Claude is up to date! instead.
These options are for version pinning, Linux package managers, npm, network storage, and verifying binary integrity.
The native installer accepts either a specific version number or a release channel (latest or stable). The channel you choose at install time becomes your default for auto-updates. See configure release channel for more information.
To install the latest version (default):
```bash theme={null} curl -fsSL https://claude.ai/install.sh | bash ``` ```powershell theme={null} irm https://claude.ai/install.ps1 | iex ``` ```batch theme={null} curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd ```To install the stable version:
```bash theme={null} curl -fsSL https://claude.ai/install.sh | bash -s stable ``` ```powershell theme={null} & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable ``` ```batch theme={null} curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd ```To install a specific version number:
```bash theme={null} curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89 ``` ```powershell theme={null} & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89 ``` ```batch theme={null} curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.89 && del install.cmd ```To confirm which version installed, run claude --version: the command prints the exact version you passed, such as 2.1.89 (Claude Code).
Claude Code publishes signed apt, dnf, and apk repositories. Each repository offers two channels: stable serves a version that is typically about one week old, skipping releases with major regressions, and latest serves every release as soon as it ships. The commands below configure the stable channel, which fits most users; each tab also shows the latest repository URL. Package manager installations do not auto-update through Claude Code; updates arrive through your normal system upgrade workflow.
All repositories are signed with the Claude Code release signing key. Before trusting the key, verify it as described in each tab.
For Debian and Ubuntu. The install commands below download the signing key with `curl` and verify it with `gpg`, which fresh Debian and Ubuntu installations may not include. If either command reports `command not found`, install both first:```bash theme={null}
sudo apt install curl gnupg
```
Download the signing key:
```bash theme={null}
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
```
If this download fails, `apt update` later fails with `NO_PUBKEY BAA929FF1A7ECACE`. Confirm the key downloaded and belongs to Anthropic before continuing:
```bash theme={null}
gpg --show-keys /etc/apt/keyrings/claude-code.asc
```
The fingerprint gpg prints should be `31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE`. If gpg reports that the file can't be opened or contains no valid OpenPGP data, the download failed or returned the wrong content: confirm your network can reach `downloads.claude.ai`, then rerun the download command.
Register the repository on the `stable` channel and install:
```bash theme={null}
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
```
To use the `latest` channel instead, both the URL path and the suite name change. Use this `deb` line:
```bash theme={null}
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/latest latest main" \
| sudo tee /etc/apt/sources.list.d/claude-code.list
```
To upgrade later, run `sudo apt update && sudo apt upgrade claude-code`.
```bash theme={null}
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
```
To use the `latest` channel instead, set `baseurl` to the `latest` repository:
```ini theme={null}
baseurl=https://downloads.claude.ai/claude-code/rpm/latest
```
dnf downloads the key on first install and prompts you to confirm the fingerprint. Verify it matches `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE` before accepting.
To upgrade later, run `sudo dnf upgrade claude-code`.
```sh theme={null}
wget -O /etc/apk/keys/claude-code.rsa.pub \
https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code
```
To switch to the `latest` channel, remove the `stable` repository line and add the `latest` repository:
```sh theme={null}
sed -i '\|downloads.claude.ai/claude-code/apk/stable|d' /etc/apk/repositories
echo "https://downloads.claude.ai/claude-code/apk/latest" >> /etc/apk/repositories
```
Verify the downloaded key with `sha256sum /etc/apk/keys/claude-code.rsa.pub`, which should report `395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6`.
To upgrade later, run `apk update && apk upgrade claude-code`.
You can also install Claude Code as a global npm package. The npm package requires Node.js 22 or later. On an older Node.js version, npm prints an EBADENGINE warning during install rather than failing; the install completes and claude still runs, since the package downloads a native binary that doesn't use your Node.js at runtime.
npm install -g @anthropic-ai/claude-codeThe npm package installs the same native binary as the standalone installer. npm pulls the binary in through a per-platform optional dependency such as @anthropic-ai/claude-code-darwin-arm64, and a postinstall step links it into place. The installed claude binary does not itself invoke Node.
Supported npm install platforms are darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, and win32-arm64. Your package manager must allow optional dependencies. See troubleshooting if the binary is missing after install.
To upgrade an npm installation, run npm install -g @anthropic-ai/claude-code@latest. Avoid npm update -g, which respects the semver range from the original install and may not move you to the newest release.
A running session reads parts of the Claude Code executable from disk as it works, not only at startup. If the file becomes unreadable mid-session, for example because it was truncated or deleted on network storage, the session crashes. On Linux, your shell reports this as a Bus error.
When home directories live on network storage, such as an NFS home mounted on several machines, lay out installs so that each session's executable stays readable until the session ends:
- Install on local disk: put the binary on each machine's local filesystem, for example with a Linux package manager or your own deployment tooling. A per-user npm prefix and the native installer's default
~/.local/share/claude/versions/directory both sit in the home directory. - Keep each version in its own directory: upgrading an npm installation in place with
npm install -gdeletes the previous binary. On storage that several machines share, that removes the file that sessions on the other machines are still running. Install each new version next to the old ones and move users to it. - Delete an old version only when no machine can still be running it: a machine can't see processes running on other machines, so checking for running processes before you delete isn't enough.
- Turn off Claude Code's own updates: set
DISABLE_UPDATESand install new versions with your own tooling. Otherwise an auto-update of an npm installation on one machine runs the same in-place upgrade and removes the binary that sessions on other machines are running. SettingDISABLE_AUTOUPDATERalone isn't enough, because users can still runclaude updateandclaude install. See Disable auto-updates.
The native installer deletes old versions from ~/.local/share/claude/versions/ on its own, which matters when that directory is on shared storage. Besides the version the launcher points to and any version a session on the same machine is running, it keeps the two newest versions and deletes the rest. A session on another machine that is running a deleted version loses its binary. With a custom launcher, Claude Code keeps every installed version and leaves cleanup to you.
Each release publishes a manifest.json containing SHA256 checksums for every platform binary. The manifest is signed with an Anthropic GPG key, so verifying the signature on the manifest transitively verifies every binary it lists.
Steps 1-3 require a POSIX shell with gpg and curl. On Windows, run them in Git Bash or WSL. Step 4 includes a PowerShell option.
```bash theme={null}
curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import
```
Display the fingerprint of the imported key.
```bash theme={null}
gpg --fingerprint security@anthropic.com
```
Confirm the output includes this fingerprint:
```text theme={null}
31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE
```
```bash theme={null}
REPO=https://downloads.claude.ai/claude-code-releases
VERSION=2.1.89
curl -fsSLO "$REPO/$VERSION/manifest.json"
curl -fsSLO "$REPO/$VERSION/manifest.json.sig"
```
```bash theme={null}
gpg --verify manifest.json.sig manifest.json
```
A valid result reports `Good signature from "Anthropic Claude Code Release Signing <security@anthropic.com>"`.
`gpg` also prints `WARNING: This key is not certified with a trusted signature!` for any freshly imported key. This is expected. The `Good signature` line confirms the cryptographic check passed. The fingerprint comparison in Step 1 confirms the key itself is authentic.
<Tabs>
<Tab title="Linux">
```bash theme={null}
sha256sum claude
```
</Tab>
<Tab title="macOS">
```bash theme={null}
shasum -a 256 claude
```
</Tab>
<Tab title="Windows PowerShell">
```powershell theme={null}
(Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()
```
</Tab>
</Tabs>
In addition to the signed manifest, individual binaries carry platform-native code signatures where supported.
- macOS: signed by "Anthropic PBC" and notarized by Apple. Verify with
codesign --verify --verbose ./claude. - Windows: signed by "Anthropic, PBC". Verify with
Get-AuthenticodeSignature .\claude.exe. - Linux: binaries are not individually code-signed. If you download directly from the
claude-code-releasesbucket or use the native installer, verify integrity with the manifest signature above. If you install with apt, dnf, or apk, your package manager verifies signatures automatically using the repository signing key.
To remove Claude Code, follow the instructions for your installation method. If claude still runs afterward, you likely have a second installation or a leftover shell alias from an older installer. See Check for conflicting installations to find and remove it.
Remove the Claude Code binary and version files:
```bash theme={null} rm -f ~/.local/bin/claude rm -rf ~/.local/share/claude ``` ```powershell theme={null} Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force ```Remove the Homebrew cask you installed. If you installed the stable cask:
brew uninstall --cask claude-codeIf you installed the latest cask:
brew uninstall --cask claude-code@latestRemove the WinGet package:
winget uninstall Anthropic.ClaudeCodeRemove the package and the repository configuration:
```bash theme={null} sudo apt remove claude-code sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc ``` ```bash theme={null} sudo dnf remove claude-code sudo rm /etc/yum.repos.d/claude-code.repo ``` ```sh theme={null} apk del claude-code sed -i '\|downloads.claude.ai/claude-code/apk|d' /etc/apk/repositories rm /etc/apk/keys/claude-code.rsa.pub ```Remove the global npm package:
npm uninstall -g @anthropic-ai/claude-codeThe VS Code extension, the JetBrains plugin, and the Desktop app also write to ~/.claude/. If any of them is still installed, the directory is recreated the next time it runs. To remove Claude Code completely, uninstall the VS Code extension, the JetBrains plugin, and the Desktop app before deleting these files.
To remove Claude Code settings and cached data:
```bash theme={null} # Remove user settings and state rm -rf ~/.claude rm ~/.claude.json# Remove project-specific settings (run from your project directory)
rm -rf .claude
rm -f .mcp.json
```
# Remove project-specific settings (run from your project directory)
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force
```