Installing Claude Code

This guide covers installing Claude Code using the Claude Code Toolbox installer. The installer uses the official native Anthropic installer by default and automatically falls back to npm if needed. All dependencies (uv, Python, Node.js) are handled automatically -- you do not need to install anything beforehand.

Quick Install

Windows

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/windows/install-claude-windows.ps1')"

macOS

curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/macos/install-claude-macos.sh | bash

Linux

curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/linux/install-claude-linux.sh | bash

The installer automatically handles all dependencies (uv, Python, Node.js if needed) and installs Claude Code using the native Anthropic installer with npm fallback.

Installation Methods

Native Installation (Default)

The native method uses official Anthropic installers (https://claude.ai/install.ps1 on Windows, https://claude.ai/install.sh on macOS and Linux) with platform-specific fallback chains. On Windows, if the native installer fails (including HTTP retry for transient 403/429/5xx errors), the installer tries GCS direct binary download before falling back to npm. On macOS and Linux, the fallback is GCS direct binary download. This is the default and recommended approach because it does not require Node.js, provides more reliable auto-updates via the official update mechanism, and supports specific version installation via direct binary download from Google Cloud Storage. On Windows, winget is used for specific version requests (CASE 2) and the winget upgrade branch.

npm Installation (Fallback)

The npm method installs via the @anthropic-ai/claude-code npm package. It requires Node.js 18+ (auto-installed if needed) and is used automatically if native installation fails in auto mode. You can force npm installation by setting CLAUDE_CODE_TOOLBOX_INSTALL_METHOD=npm.

Auto Mode (Default Behavior)

In auto mode (the default), the installer tries the full native fallback chain first: native installer (with HTTP retry for transient errors), then GCS direct binary download on all platforms. If all native methods fail, it automatically falls back to npm. This is the recommended approach for most users and requires no additional configuration.

GCS Direct Download: Platform Selection and Integrity Verification

The GCS direct download selects the binary matching the host platform and architecture: win32-x64 or win32-arm64 on Windows, darwin-x64 or darwin-arm64 on macOS, and linux-x64 or linux-arm64 on Linux, with the musl variants (linux-x64-musl, linux-arm64-musl) selected automatically on Alpine Linux (detected via /etc/alpine-release). On an unrecognized architecture, the installer reports an explicit error and aborts the GCS download instead of fetching a binary that cannot execute on the machine.

Every GCS download is verified against the release manifest ({version}/manifest.json in the same GCS bucket), which lists the expected SHA-256 checksum and exact byte size for each platform binary. Verification fails closed: if the manifest cannot be fetched, or the downloaded file's size or checksum does not match, the download is rejected and the temporary file is deleted. After installation, the installer additionally runs claude --version on the installed binary (on the native-installer and GCS paths across all platforms); a binary that exists but cannot execute fails verification and triggers the recovery chain or the next fallback method.

Environment Variables

CLAUDE_CODE_TOOLBOX_INSTALL_METHOD

Controls which installation method the installer uses.

Value	Behavior
auto (default)	Try native installation first (including GCS direct download), fall back to npm if needed
native	Use only native methods (native installer, GCS direct download), no npm fallback
npm	Use only npm installer, requires Node.js 18+

Invalid values default to auto with a warning.

Linux/macOS example:

CLAUDE_CODE_TOOLBOX_INSTALL_METHOD=native curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/linux/install-claude-linux.sh | bash

Windows example:

powershell -NoProfile -ExecutionPolicy Bypass -Command "$env:CLAUDE_CODE_TOOLBOX_INSTALL_METHOD='npm'; iex (irm 'https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/windows/install-claude-windows.ps1')"

CLAUDE_CODE_TOOLBOX_VERSION

Specify a particular version to install (e.g., 2.0.76). All installation methods support version pinning: native via direct binary download from Google Cloud Storage and npm. On Windows, winget is used for specific version requests (CASE 2) and the winget upgrade branch. Auto-update management is handled by setup_environment.py when used; see the Environment Configuration Guide for details. If the requested version is not available via one method, the installer cascades through the fallback chain (e.g., GCS → winget with --version → native installer "latest" → npm on Windows for specific version requests).

Linux/macOS example:

CLAUDE_CODE_TOOLBOX_VERSION=2.0.76 curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/linux/install-claude-linux.sh | bash

Windows example:

powershell -NoProfile -ExecutionPolicy Bypass -Command "$env:CLAUDE_CODE_TOOLBOX_VERSION='2.0.76'; iex (irm 'https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/windows/install-claude-windows.ps1')"

CLAUDE_CODE_TOOLBOX_ALLOW_ROOT

Set to exactly 1 to allow running as root on Linux/macOS. Only the exact string 1 is accepted -- true, yes, and empty strings do NOT work. By default, the installer refuses to run as root because running as root creates configuration under /root/ instead of the regular user's home directory. Use this for Docker containers, CI/CD pipelines, or other legitimate root execution environments.

CLAUDE_CODE_TOOLBOX_ALLOW_ROOT=1 curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/linux/install-claude-linux.sh | bash

What the Installer Does

The bootstrap scripts install uv (Astral's Python package manager) and Python 3.12 automatically before running the main installer. The bootstrap scripts download the main installer (install_claude.py) to a temporary file before execution. This avoids the Linux kernel MAX_ARG_STRLEN limit (128 KiB per argument) that prevents large scripts from being passed via stdin pipe. The main installer then performs the following steps.

Windows (4 steps):

1. Checks and installs Git Bash if not present (required for scripts that need bash.exe)
2. Checks Node.js availability (only installs Node.js if the npm method will be used)
3. Configures the environment (PowerShell execution policy, PATH updates)
4. Installs Claude Code CLI (native-first, npm fallback)

macOS and Linux (3 steps):

1. Checks Node.js availability (only installs Node.js if the npm method will be used)
2. Skips Git Bash and environment configuration (not needed on Unix platforms)
3. Installs Claude Code CLI (native-first, npm fallback)

Upgrades and Switching Methods

Automatic Upgrades

When Claude Code is already installed, the installer checks for updates against the npm registry and upgrades using the same method that was originally used (source-matching). Native installations are upgraded via the native installer, npm installations are upgraded via npm, winget installations try winget upgrade first with npm fallback, and unknown-source installations try native first with npm fallback.

Upgrade Version Verification

After each upgrade attempt, the installer verifies that the binary was actually updated to the expected version. If a version mismatch is detected (the installer reported success but the binary remains at the old version), a recovery cascade activates:

1. Versions cache recovery -- The Anthropic native installer downloads binaries to ~/.local/share/claude/versions/ before promotion. If the promotion step fails silently, the installer copies the correct binary from this cache to ~/.local/bin/.
2. GCS direct download -- Downloads the correct version directly from Google Cloud Storage, bypassing the native installer entirely.
3. npm fallback (auto mode only) -- Installs the correct version via npm as a last resort. Skipped in native mode.
4. Graceful degradation -- If all recovery methods fail, the installer continues with the current version and displays a warning. The installation is never blocked by an upgrade failure.

The npm upgrade branch does not use the recovery cascade (versions cache and GCS are native-specific mechanisms). Instead, it verifies the version and logs a warning on mismatch.

This verification addresses a known issue where the Anthropic native installer may report a successful upgrade but fail to replace the binary (#14942).

Auto-Migration from npm to Native

In auto mode, when an npm installation is detected, the installer automatically attempts to migrate to the native installer for better stability. On successful migration, the old npm installation is removed to prevent PATH conflicts. If npm removal fails (due to permission issues in non-interactive mode), the installer displays a prominent warning with manual removal instructions but does not block the native installation.

Source Detection

The installer classifies the existing installation by examining the binary path.

Path Pattern	Detected Source	Upgrade Method
Contains npm or .npm-global	npm	npm directly
Contains .local/bin or .claude/bin	native	Native installer
Contains /usr/local/bin	unknown	Native-first, npm fallback
Windows: Programs\claude (legacy winget/native)	winget or native	Via _classify_localappdata_claude()
Windows: WinGet\Links or WinGet\Packages	winget	winget upgrade, then npm fallback
Any other path	unknown	Native-first, npm fallback
Not found	none	Fresh install

Install Method Recording

After a successful installation or upgrade, the installer records the method in ~/.claude.json under the installMethod key so that Claude Code's own tooling (such as claude doctor) reports the installation type correctly. The values written are native (native installer or GCS direct download), global (npm global installs), and winget (Windows package manager installs). Claude Code itself recognizes native, global, and local, and reports a missing value as unknown. When setup_environment.py creates an isolated environment (command-names in YAML), it propagates this recorded value into the isolated .claude.json so isolated sessions report the same installation type -- see global-config in the Environment Configuration Guide.

Switching from npm to Native

To switch manually, uninstall the npm version with npm uninstall -g @anthropic-ai/claude-code, then run the installer again. It will use the native method by default. All Claude Code configurations are preserved since both installation methods use the same configuration directory.

Auto-Update Management

Auto-update management is handled by setup_environment.py via YAML configuration, not by the standalone installer. When claude-code-version is specified in a YAML environment configuration, setup_environment.py automatically manages auto-update controls across four targets.

For version pinning with auto-update protection, use setup_environment.py with a YAML configuration specifying claude-code-version. See Automatic Auto-Update Management in the Environment Configuration Guide.

Known Issues

The Claude Code auto-updater may ignore disable settings in some versions:

• #10764 -- Auto-updater runs despite DISABLE_AUTOUPDATER
• #11263 -- Auto-update still triggers in some scenarios
• #12564 -- Auto-updater bypass in certain conditions

Troubleshooting

Native Installation Fails

The installer automatically tries GCS direct download before falling back to npm in auto mode, so most users do not need to take any action. To isolate the issue, use CLAUDE_CODE_TOOLBOX_INSTALL_METHOD=native to see only native method output without the npm fallback. You can also try the native installer directly:

• Windows: irm https://claude.ai/install.ps1 | iex
• macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash

Corrupt or Incompatible Binary Detected

If the existing claude binary exists but cannot be launched -- Windows reports WinError 193 (bad executable format) or WinError 216 (architecture mismatch), and Unix-like systems report ENOEXEC -- the installer's version probe classifies the condition as a recoverable corrupt installation. It prints a warning that the binary "cannot execute on this machine (corrupt or architecture mismatch)" and quarantines the native binary before reinstalling: on Windows the file is renamed to claude.exe.old (cleaned up automatically on the next run), and on Linux/macOS it is removed. Quarantining happens before any installation method runs, so a broken native binary can no longer shadow a working npm installation. No manual action is needed -- the normal installation flow then installs a fresh binary and verifies that it executes.

Winget Version Not Available (Windows)

When requesting a specific version via CLAUDE_CODE_TOOLBOX_VERSION, winget may fail if the version has not yet been published to the winget manifest repository (microsoft/winget-pkgs). Winget manifests typically lag official releases by hours to days. The installer detects this condition and automatically falls through to the next available method (native installer with "latest", then npm). A warning message indicates when this manifest lag is the likely cause.

Node.js v25+ Compatibility

Node.js v25+ removed the SlowBuffer API that Claude Code's npm package depends on. This does NOT affect native installations, which do not require Node.js. If you must use the npm method, downgrade to Node.js v22 or v20 LTS:

• macOS: brew uninstall node && brew install node@22 && brew link --force --overwrite node@22
• Linux: nvm install 22 && nvm use 22
• Windows: Download Node.js 22 LTS from https://nodejs.org/

Root Guard

The installer refuses to run as root by default because running as root creates configuration under /root/ instead of your home directory. Run as your regular user -- the installer requests sudo only when needed (for npm global installs). Override with CLAUDE_CODE_TOOLBOX_ALLOW_ROOT=1 for Docker or CI environments.

npm Version Still Runs After Native Install

If you installed the native version but claude --version still shows the old npm version, you may have both installations present and PATH ordering causes the npm binary to take precedence. The installer attempts automatic npm removal during native installation but it can fail silently in non-interactive environments (such as curl | bash without cached sudo credentials).

Symptoms: A prominent boxed warning during installation stating "npm Claude Code installation was NOT removed", or which claude pointing to a path containing npm or /usr/local/bin instead of ~/.local/bin.

Fix: Remove the npm installation files directly and restart your terminal:

# Determine your npm global prefix
npm config get prefix
# Output is typically /usr or /usr/local

# Remove using the prefix (replace /usr with your prefix if different)
sudo rm -rf /usr/lib/node_modules/@anthropic-ai/.claude-code-* /usr/lib/node_modules/@anthropic-ai/claude-code
sudo rm -f /usr/bin/claude

On Windows (run as Administrator):

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

After removal, restart your terminal session so that claude resolves to the native binary at ~/.local/bin/claude.

npm Removal Fails with ENOTEMPTY

If removing the npm installation fails with an error like ENOTEMPTY: directory not empty, rename ... -> .../.claude-code-ZjqcDZyQ, this is a known npm bug. The npm package manager creates temporary directories during uninstall, and if a stale temporary directory from a prior interrupted operation already exists, the rename fails.

This issue is more common in WSL2 environments due to cross-filesystem interactions and VS Code Remote WSL file watchers holding handles on node_modules directories, but it can occur on any platform.

Fix: Remove the files directly instead of using npm uninstall:

# Determine your npm global prefix
npm config get prefix
# Output is typically /usr or /usr/local

# Remove using the prefix (replace /usr with your prefix if different)
sudo rm -rf /usr/lib/node_modules/@anthropic-ai/.claude-code-* /usr/lib/node_modules/@anthropic-ai/claude-code
sudo rm -f /usr/bin/claude
# Optionally clean up the empty parent directory
sudo rmdir /usr/lib/node_modules/@anthropic-ai 2>/dev/null || true

The .claude-code-* glob pattern removes stale temporary directories that prevent npm from operating. After removal, restart your terminal.

Note: The installer automatically attempts this direct removal when npm uninstall fails. This manual procedure is only needed if the automatic fallback also fails (e.g., in non-interactive environments without cached sudo credentials).

Upgrade Reports Wrong Version

If the installer reports upgrading to a new version but claude --version still shows the old version, the post-upgrade verification should detect this automatically and attempt recovery. If automatic recovery also fails, the installer logs a warning with the expected and actual versions. To resolve manually:

1. Set CLAUDE_CODE_TOOLBOX_VERSION=<desired_version> and re-run the installer to force a specific version
2. Check if the correct binary exists in ~/.local/share/claude/versions/<version>/ -- if present, copy it manually to ~/.local/bin/claude (or claude.exe on Windows)
3. As a last resort, use CLAUDE_CODE_TOOLBOX_INSTALL_METHOD=npm to install via npm instead

Claude Command Not Found After Install

If claude is not available after installation, open a new terminal session. The installer updates PATH but the current session may not reflect the change.

Corporate Proxy or Firewall

The installer includes SSL fallback for corporate environments with custom certificates. If downloads fail, check your firewall rules for access to claude.ai, storage.googleapis.com, and registry.npmjs.org.