The Claude Code install is one command. When it fails, the error message tells you which of about a dozen known failure modes you hit: a PATH missing ~/.local/bin, an npm global prefix owned by root, a WSL1 loader that cannot execute the binary, or a corporate proxy intercepting TLS.
This page indexes every documented install failure by its exact error text, with the exact fix. If your install worked and you want the standard setup steps instead, see the Claude Code install guide.
Error Lookup Table
Match what your terminal printed to the fix. Each row links to a section below with the full commands.
| Error message | Cause | Fix |
|---|---|---|
| command not found: claude / 'claude' is not recognized | ~/.local/bin not in PATH | Fix 1: add install dir to PATH |
| npm EACCES / permission denied | npm global prefix owned by root | Fix 2: switch to native installer, never sudo npm |
| syntax error near unexpected token '<' / curl: (22) 403 | Install URL returned HTML or error page | Fix 3: region/network check, brew or winget fallback |
| unable to get local issuer certificate / TLS connect error | TLS-inspecting corporate proxy | Fix 4: --cacert + NODE_EXTRA_CA_CERTS |
| cannot execute binary file: Exec format error | WSL1 loader regression | Fix 5: wsl --set-version 2 |
| exec: node: not found (WSL) | WSL using Windows Node from /mnt/c/ | Fix 6: install Linux Node via nvm |
| 'irm' is not recognized / '&&' is not valid | Wrong shell for the install command | Fix 7: match command to CMD vs PowerShell |
| requires either Git for Windows (for bash) or PowerShell | Neither shell found | Fix 8: CLAUDE_CODE_GIT_BASH_PATH |
| Old version runs after update | Duplicate npm + native binaries | Fix 9: which -a claude, remove extras |
| dyld: cannot load / Symbol not found | macOS older than 13.0 | Fix 10: update macOS |
| Killed during install / Error loading shared library | Out of memory, or musl missing libs | Fix 11: add swap; apk add libgcc libstdc++ ripgrep |
| cannot be used with root/sudo privileges | Bypass mode blocked as root | Fix 12: run as non-root user |
First diagnostic: claude doctor
If claude starts at all, run claude doctor from your shell for an automated check of installation type, PATH, auth state, and configuration. Most of the fixes below are what doctor would point you at.
1. "command not found: claude" After Installation
The most common failure. The install succeeded, but the binary lives at ~/.local/bin/claude on macOS/Linux (or %USERPROFILE%\.local\bin\claude.exe on Windows) and that directory is not in your shell's PATH. The exact wording varies: zsh: command not found: claude on macOS, bash: claude: command not found on Linux, 'claude' is not recognized on Windows.
Check whether the install directory is on your PATH:
Check PATH (macOS/Linux)
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"No output means it is missing. Add it to your shell config:
Add ~/.local/bin to PATH
# Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Bash (most Linux distros)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --versionOn Windows PowerShell, append the directory to your User PATH and restart the terminal:
Windows PowerShell PATH fix
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')A subtler Windows variant: an older Claude Desktop install registers a Claude.exe in WindowsApps that takes PATH priority, so claude opens the desktop app instead of the CLI. Updating Claude Desktop fixes it.
2. npm EACCES Permission Errors
npm install -g @anthropic-ai/claude-code fails with EACCES when the npm global prefix is owned by root. The instinctive fix, sudo npm install -g, is the one thing Anthropic's docs explicitly say never to do: it creates root-owned files that break future updates and is a security risk.
The documented fix is to stop using npm for this. The native installer requires no root, no Node.js, and auto-updates in the background:
Replace npm install with the native installer
curl -fsSL https://claude.ai/install.sh | bashIf the native installer itself hits permission errors, the target directories are not writable by your user. Check and repair ownership:
Fix directory ownership
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.localIf you must stay on npm (corporate mirror, lockfile pinning), it needs Node.js 18+ and the package pulls the native binary through per-platform optional dependencies like @anthropic-ai/claude-code-darwin-arm64. Installing with --omit=optional (or optional=false in .npmrc) skips the binary entirely and produces Could not find native binary package at runtime. There is no JavaScript fallback. Upgrade with npm install -g @anthropic-ai/claude-code@latest, not npm update -g. Full npm walkthrough: npm install claude code.
3. "syntax error near unexpected token '<'" (Install Script Returns HTML)
Bash tried to execute an HTML page. You will see one of:
Symptoms
bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'
# PowerShell equivalent
Invoke-Expression: Missing argument in parameter list.
# Or a bare error status
curl: (22) The requested URL returned error: 403The install URL returned an HTML page or an error status instead of the script. If the page says "App unavailable in region," Claude Code is not available in your country. A bare 403 can also come from a corporate proxy blocking the download. Test connectivity to the actual download host:
Verify you can reach downloads.claude.ai
curl -sI https://downloads.claude.ai/claude-code-releases/latest
# HTTP/2 200 = reachable; retry the installer
# "Could not resolve host" or timeout = network is blocking itIn PowerShell use curl.exe -sI; PowerShell aliases curl to Invoke-WebRequest, which rejects those flags. If the network is fine and the error persists, use a package manager instead. They install the same binary:
Alternative installers
# macOS
brew install --cask claude-code
# Windows
winget install Anthropic.ClaudeCode4. TLS Errors and Corporate Proxy Failures
Errors like curl: (35) TLS connect error, unable to get local issuer certificate, SELF_SIGNED_CERT_IN_CHAIN, or PowerShell's Could not establish trust relationship for the SSL/TLS secure channel mean the TLS handshake failed, almost always because a corporate proxy is inspecting traffic with its own certificate.
Two separate things need the corporate CA bundle: the install download, and Claude Code's own API requests after install.
Install through a TLS-inspecting proxy
# 1. Point curl at your corporate CA bundle for the download
curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
# 2. Make Claude Code trust the same bundle for API calls
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pemIf the proxy requires you to route through it at all, set the standard proxy variables before installing. Claude Code respects HTTPS_PROXY, HTTP_PROXY, and NO_PROXY; it does not support SOCKS proxies. Basic auth goes in the URL: export HTTPS_PROXY=http://username:password@proxy.example.com:8080.
Proxy environment variables
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bashWindows-specific TLS fixes:
- Old PowerShell defaults: enable TLS 1.2 first with
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12, thenirm https://claude.ai/install.ps1 | iex. CRYPT_E_NO_REVOCATION_CHECKorCRYPT_E_REVOCATION_OFFLINE: your firewall blocks certificate revocation lookups. Add--ssl-revoke-best-effortto the CMD install command, or usewinget install Anthropic.ClaudeCodewhich avoids curl.
Network allowlist for IT: Claude Code needs api.anthropic.com (API), claude.ai and platform.claude.com (auth), and downloads.claude.ai (installer and auto-updater). For routing all model traffic through an internal gateway instead, see Claude Code with LiteLLM.
5. "Exec format error" on WSL1 (and WSL1 vs WSL2)
If claude in WSL prints cannot execute binary file: Exec format error, you are on WSL1 and hitting a known native-binary regression (anthropics/claude-code issue #38788): the binary's program headers changed in a way WSL1's loader cannot handle. WSL2 is also the only WSL version Claude Code's sandboxing supports; native Windows and WSL1 are unsupported for sandboxing.
The clean fix is converting the distro to WSL2 from PowerShell:
Convert to WSL2
wsl --set-version <DistroName> 2If you must stay on WSL1, invoke the binary through the dynamic linker by adding this function to ~/.bashrc:
WSL1 workaround
claude() {
/lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}One more WSL note: keep projects on the Linux filesystem (/home/), not /mnt/c/. Cross-filesystem reads are slow enough that Claude Code's search returns fewer results than expected, and /doctor reports Search as OK while it happens.
6. "exec: node: not found" in WSL
This applies only if you installed via npm inside WSL (the native installer has no Node dependency). WSL imports the Windows PATH by default, so npm and node may resolve to the Windows binaries under /mnt/c/. Confirm:
Diagnose Windows Node leaking into WSL
which npm
which node
# Paths starting with /mnt/c/ = Windows binaries (the problem)
# Paths starting with /usr/ = Linux binaries (correct)Two documented fixes:
- OS detection errors during npm install: run
npm config set os linux, thennpm install -g @anthropic-ai/claude-code --force. No sudo. exec: node: not foundat runtime: install Linux Node via your distro's package manager or nvm, and make sure nvm loads in your shell (source ~/.nvm/nvm.sh). If Windows paths still win, prepend the Linux Node path:export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH".
Do not set appendWindowsPath = false to fix this; it breaks calling Windows executables from WSL. The simpler exit is the native installer, which sidesteps Node entirely: curl -fsSL https://claude.ai/install.sh | bash works identically inside WSL.
7. "irm Is Not Recognized" and Other Wrong-Shell Errors on Windows
Windows has three shells and three different install commands. Copying the wrong one produces three distinct errors:
| Error you saw | You are in | Run instead |
|---|---|---|
| 'irm' is not recognized | CMD | curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd |
| The token '&&' is not valid | PowerShell (ran the CMD command) | irm https://claude.ai/install.ps1 | iex |
| 'bash' is not recognized as the name of a cmdlet | PowerShell (ran the macOS/Linux command) | irm https://claude.ai/install.ps1 | iex |
Two more Windows-only traps: Claude Code does not support 32-bit Windows usually means you opened the "Windows PowerShell (x86)" Start menu entry on a 64-bit machine; run [Environment]::Is64BitOperatingSystem, and if it prints True, reopen plain "Windows PowerShell". And The process cannot access the file ... because it is being used by another process means a previous installer run or an antivirus scan holds a partial download; delete %USERPROFILE%\.claude\downloads and rerun the installer.
8. "Requires Either Git for Windows (for bash) or PowerShell"
Git for Windows is optional; Claude Code falls back to a PowerShell tool when Git Bash is absent. This error means it found neither shell. If PowerShell is missing from PATH, its default location is C:\Windows\System32\WindowsPowerShell\v1.0\; add that, or install PowerShell 7.
If Git is installed but not detected, point Claude Code at it in settings.json:
settings.json
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}Find the real path with where.exe git and use the bin\bash.exe under that directory. If the path is correct and the error persists, endpoint security (AppLocker, EDR) may be blocking the check: versions before v2.1.116 spawned cmd.exe to verify the path, which those policies block. Update Claude Code first; if it still fails, have IT allowlist claude.exe, cmd.exe, and bash.exe.
9. Duplicate Binaries: Migrating npm Install to Native Cleanly
Symptom: you updated Claude Code but claude --version shows an old version, or behavior differs between terminals. Cause: multiple installations, and PATH order decides which one runs. There are three places a claude binary can come from:
Find every installed copy
which -a claude
ls -la ~/.local/bin/claude # native installer
ls -la ~/.claude/local/ # legacy local npm install
npm -g ls @anthropic-ai/claude-code 2>/dev/null # npm globalKeep one. Anthropic recommends the native install at ~/.local/bin/claude (it auto-updates in the background). Remove the others:
Remove duplicate installs
# npm global
npm uninstall -g @anthropic-ai/claude-code
# legacy local npm install
rm -rf ~/.claude/local
# Homebrew (use claude-code@latest if you installed that cask)
brew uninstall --cask claude-code
# WinGet (PowerShell)
winget uninstall Anthropic.ClaudeCodeThen verify exactly one remains with which -a claude and run claude doctor to confirm the installation type.
10. macOS: dyld Errors, Apple Silicon vs Intel, Homebrew vs curl
dyld: cannot load, dyld: Symbol not found: _ubrk_clone, or Abort trap: 6 mean your macOS is older than the binary supports. Claude Code requires macOS 13.0+. Updating macOS is the only fix; Homebrew downloads the same binary, so switching installers does not help.
Architecture errors are different: Illegal instruction means an x64 binary on ARM (or a pre-2013 CPU without AVX, common on cheap VPSes). Check with uname -m: arm64 is Apple Silicon, x86_64 is Intel. The installer detects this automatically; via npm, the per-platform optional dependency (claude-code-darwin-arm64 vs claude-code-darwin-x64) must match, which is one reason corporate npm mirrors that skip platform packages break installs.
The Homebrew-vs-curl conflict is about updates, not the binary. brew install --cask claude-code tracks the stable channel about a week behind and never auto-updates (you run brew upgrade claude-code); the curl installer auto-updates in the background. Installing both leaves two binaries on PATH and a version that appears to never update (Fix 9). Pick one.
11. Linux: "Killed" During Install and Alpine Library Errors
Killed mid-install on a VPS means the Linux OOM killer terminated the installer. Claude Code requires 4 GB+ RAM. On a small instance, add swap:
Add 2 GB swap, then retry
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
curl -fsSL https://claude.ai/install.sh | bashError loading shared library libstdc++.so.6 has two cases. On Alpine and other musl-based distros (3.19+ supported), install the required packages and tell Claude Code to use the system ripgrep:
Alpine / musl requirements
apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0On glibc systems (check with ldd --version), the installer may have misdetected musl because cross-compilation packages are present; remove the install and reinstall. In Docker, two more rules: set WORKDIR before the install (running from / scans the whole filesystem and hangs) and build with --memory=4g if Docker Desktop caps memory lower. Distro-specific package-manager installs (signed apt/dnf/apk repos at downloads.claude.ai) are covered in Claude Code on Linux.
12. Installed Fine but Won't Start: Root and Auth Failures
"--dangerously-skip-permissions cannot be used with root/sudo privileges"
That is the exact message, and it is deliberate: on Linux and macOS, Claude Code refuses to start in bypass mode as root. The check is skipped inside a recognized sandbox; for containers, Anthropic's devcontainer config runs Claude Code as a non-root user, which is the supported pattern. Create a non-root user rather than patching around the check. Details on the flag: claude code dangerously skip permissions.
403 Forbidden after login
Installing is free; running is not. Claude Code requires Pro ($17/mo annual, $20 monthly), Max 5x ($100/mo), Max 20x ($200/mo), Team, Enterprise, or a Console account billed at API rates. The free Claude.ai plan does not include Claude Code access. Console users additionally need the "Claude Code" or "Developer" role assigned in Console settings. Plan comparison: Claude Code pricing.
"This organization has been disabled" with an active subscription
A stale ANTHROPIC_API_KEY in your shell profile is overriding your subscription login, typically an old key from a previous employer or project. Run unset ANTHROPIC_API_KEY, remove the export line from ~/.zshrc / ~/.bashrc, and confirm the active auth method with /status inside Claude Code.
OAuth login fails in WSL2, SSH, or containers
The browser opens on a different host, so the redirect cannot reach Claude Code's local callback. Paste the login code the browser shows into the terminal prompt, or run claude auth login, which reads the code from stdin. From WSL2, point BROWSER at your Windows browser: export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe".
Clean Uninstall and Reinstall
When an install is wedged beyond diagnosis, removing everything and reinstalling takes under a minute:
Full removal (macOS/Linux/WSL)
# Binary and shared data
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
# Optional: settings, MCP config, and session history
rm -rf ~/.claude
rm ~/.claude.json
# Reinstall
curl -fsSL https://claude.ai/install.sh | bashThe second block deletes your history
~/.claude and ~/.claude.json hold settings, MCP server config, and all session history. Skip those two lines if you only want a fresh binary.
To pin a version instead of reinstalling latest, pass it to the installer: curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89, or track the stable channel with bash -s stable. In settings, {"autoUpdatesChannel": "stable"} keeps you about a week behind latest, and DISABLE_AUTOUPDATER="1" turns background updates off entirely.
Verify the Install
Three verification commands
claude --version # prints the installed version
claude doctor # full diagnostic: install type, PATH, auth, config
claude update # applies any pending update immediatelySystem requirements, for reference: macOS 13.0+, Windows 10 1809+ or Server 2019+, Ubuntu 20.04+/Debian 10+/Alpine 3.19+, 4 GB+ RAM, x64 or ARM64, and one of Bash, Zsh, PowerShell, or CMD. Windows needs no admin rights. If the terminal itself is the problem, the Desktop app for macOS and Windows installs Claude Code with no command line at all.
Once it runs, the next failure surface is configuration, not installation: settings.json for permissions and env, hooks for automation, and the VS Code extension if you want it in an editor.
Frequently Asked Questions
Why do I get "command not found: claude" after installing Claude Code?
The binary installed to ~/.local/bin/claude but that directory is not in your PATH. Add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc or ~/.bashrc, open a new terminal, and run claude --version. Full steps in Fix 1.
How do I fix npm EACCES errors when installing Claude Code?
Never sudo npm install -g. Switch to the native installer (curl -fsSL https://claude.ai/install.sh | bash), which needs no root and no Node.js. If ~/.local itself is root-owned, run sudo chown -R $(whoami) ~/.local first.
Do I need Node.js to install Claude Code?
No. Only the npm route needs Node.js 18+, and even there the installed claude binary is native and never invokes Node. The curl, PowerShell, Homebrew, WinGet, and apt/dnf/apk methods have no Node dependency.
Does Claude Code work on WSL1?
WSL1 hits a known Exec format error regression (issue #38788) and is excluded from sandboxing support (WSL2 only). Convert with wsl --set-version <DistroName> 2, or use the /lib64/ld-linux-x86-64.so.2 workaround in Fix 5 if you must stay on WSL1.
Why does Claude Code refuse to start as root?
Bypass-permissions mode is blocked for root/sudo on Linux and macOS with the message --dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons. Run as a non-root user; in containers, mirror Anthropic's devcontainer setup, which uses a non-root user.
Is Claude Code free to install?
The install is free. Usage requires Pro ($17/mo billed annually, $20 monthly), Max ($100 or $200/mo), Team, Enterprise, or a Console account at API rates. The free Claude.ai plan does not include Claude Code.
How do I completely uninstall and reinstall Claude Code?
rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude removes the binary; rm -rf ~/.claude && rm ~/.claude.json additionally wipes settings, MCP config, and session history. Reinstall with the curl installer.
Installed? Make the Agent Search Faster
WarpGrep is agentic code search that plugs into Claude Code as an MCP server: 8 parallel tool calls per turn, sub-6s searches, free for 100k requests ($1/1M on Pro). Better retrieval means fewer wrong-file edits.