Advanced setup - Claude Code Docs

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.

System requirements

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
Network: internet connection required. See network configuration.
Shell: Bash, Zsh, PowerShell, or CMD. On Windows, Git for Windows is required.
Location: Anthropic supported countries

Additional dependencies

ripgrep: usually included with Claude Code. If search fails, see search troubleshooting.

Install Claude Code

Prefer a graphical interface? The Desktop app lets you use Claude Code without the terminal. Download it for macOS or Windows.New to the terminal? See the terminal guide for step-by-step instructions.

To install Claude Code, use one of the following methods:

Native Install (Recommended)
Homebrew
WinGet

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

If you see The token '&&' is not a valid statement separator, you’re in PowerShell, not CMD. Use the PowerShell command above instead. Your prompt shows PS C:\ when you’re in PowerShell.Windows requires Git for Windows. Install it first if you don’t have it.

Native installations automatically update in the background to keep you on the latest version.

brew install --cask claude-code

Homebrew installations do not auto-update. Run brew upgrade claude-code periodically to get the latest features and security fixes.

winget install Anthropic.ClaudeCode

WinGet installations do not auto-update. Run winget upgrade Anthropic.ClaudeCode periodically to get the latest features and security fixes.

After installation completes, open a terminal in the project you want to work in and start Claude Code:

claude

If you encounter any issues during installation, see the troubleshooting guide.

Set up on Windows

Claude Code on Windows requires Git for Windows or WSL. You can launch claude from PowerShell, CMD, or Git Bash. Claude Code uses Git Bash internally to run commands. You do not need to run PowerShell as Administrator. Option 1: Native Windows with Git Bash Install Git for Windows, then run the install command from PowerShell or CMD. If Claude Code can’t find your Git Bash installation, set the path in your settings.json file:

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

Claude Code can also run PowerShell natively on Windows as an opt-in preview. See PowerShell tool for setup and limitations. Option 2: WSL Both WSL 1 and WSL 2 are supported. WSL 2 supports sandboxing for enhanced security. WSL 1 does not support sandboxing.

Alpine Linux and musl-based distributions

The native installer on Alpine and other musl/uClibc-based distributions requires libgcc, libstdc++, and ripgrep. Install these using your distribution’s package manager, then set USE_BUILTIN_RIPGREP=0. This example installs the required packages on Alpine:

apk add libgcc libstdc++ ripgrep

Then set USE_BUILTIN_RIPGREP to 0 in your settings.json file:

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

Verify your installation

After installing, confirm Claude Code is working:

claude --version

For a more detailed check of your installation and configuration, run claude doctor:

claude doctor

Authenticate

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 Vertex AI, or Microsoft Foundry. After installing, log in by running claude and following the browser prompts. See Authentication for all account types and team setup options.

Update Claude Code

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 and WinGet installations require manual updates.

Auto-updates

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.

Homebrew and WinGet installations do not auto-update. Use brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode to update manually.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 claude-code periodically to reclaim disk space.

Configure release channel

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"
}

For enterprise deployments, you can enforce a consistent release channel across your organization using managed settings.

Disable auto-updates

Set DISABLE_AUTOUPDATER to "1" in the env key of your settings.json file:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Update manually

To apply an update immediately without waiting for the next background check, run:

claude update

Advanced installation options

These options are for version pinning, migrating from npm, and verifying binary integrity.

Install a specific version

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):

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

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

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

To install the stable version:

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

To install a specific version number:

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

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

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

Deprecated npm installation

npm installation is deprecated. The native installer is faster, requires no dependencies, and auto-updates in the background. Use the native installation method when possible.

Migrate from npm to native

If you previously installed Claude Code with npm, switch to the native installer:

# Install the native binary
curl -fsSL https://claude.ai/install.sh | bash

# Remove the old npm installation
npm uninstall -g @anthropic-ai/claude-code

You can also run claude install from an existing npm installation to install the native binary alongside it, then remove the npm version.

Install with npm

If you need npm installation for compatibility reasons, you must have Node.js 18+ installed. Install the package globally:

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

Do NOT use sudo npm install -g as this can lead to permission issues and security risks. If you encounter permission errors, see troubleshooting permission errors.

Binary integrity and code signing

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.

Verify the manifest signature

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.

Download and import the public key

The release signing key is published at a fixed URL.

curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import

Display the fingerprint of the imported key.

gpg --fingerprint security@anthropic.com

Confirm the output includes this fingerprint:

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

Download the manifest and signature

Set VERSION to the release you want to verify.

REPO=https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases
VERSION=2.1.89
curl -fsSLO "$REPO/$VERSION/manifest.json"
curl -fsSLO "$REPO/$VERSION/manifest.json.sig"

Verify the signature

Verify the detached signature against the manifest.

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.

Check the binary against the manifest

Compare the SHA256 checksum of your downloaded binary with the value listed under platforms.<platform>.checksum in manifest.json.

Linux
macOS
Windows PowerShell

sha256sum claude

shasum -a 256 claude

(Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()

Manifest signatures are available for releases from 2.1.89 onward. Earlier releases publish checksums in manifest.json without a detached signature.

Platform code signatures

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: use the manifest signature above to verify integrity. Linux binaries are not individually code-signed.

Uninstall Claude Code

To remove Claude Code, follow the instructions for your installation method.

Native installation

Remove the Claude Code binary and version files:

macOS, Linux, WSL
Windows PowerShell

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew installation

Remove the Homebrew cask:

brew uninstall --cask claude-code

WinGet installation

Remove the WinGet package:

winget uninstall Anthropic.ClaudeCode

npm

Remove the global npm package:

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

Remove configuration files

Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.

To remove Claude Code settings and cached data:

macOS, Linux, WSL
Windows PowerShell

# 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 user settings and state
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

# Remove project-specific settings (run from your project directory)
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force

Administration

​System requirements

​Additional dependencies

​Install Claude Code

​Set up on Windows

​Alpine Linux and musl-based distributions

​Verify your installation

​Authenticate

​Update Claude Code

​Auto-updates

​Configure release channel

​Disable auto-updates

​Update manually

​Advanced installation options

​Install a specific version

​Deprecated npm installation

​Migrate from npm to native

​Install with npm

​Binary integrity and code signing

​Verify the manifest signature

​Platform code signatures

​Uninstall Claude Code

​Native installation

​Homebrew installation

​WinGet installation

​npm

​Remove configuration files

System requirements

Additional dependencies

Install Claude Code

Set up on Windows

Alpine Linux and musl-based distributions

Verify your installation

Authenticate

Update Claude Code

Auto-updates

Configure release channel

Disable auto-updates

Update manually

Advanced installation options

Install a specific version

Deprecated npm installation

Migrate from npm to native

Install with npm

Binary integrity and code signing

Verify the manifest signature

Platform code signatures

Uninstall Claude Code

Native installation

Homebrew installation

WinGet installation

npm

Remove configuration files