Skip to content

installing-claude-code.md

Latest commit

 

History

History
252 lines (156 loc) · 16.9 KB

installing-claude-code.md

File metadata and controls

252 lines (156 loc) · 16.9 KB

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.

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

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

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.