Claude Code Install Errors (2026): 15 Fixes for npm EACCES, PATH, WSL & Windows Failures

Recent Installer and Updater Changes

Dated from the Claude Code changelog and GitHub issues. Newest first.

• Sep 22, 2026 (v2.1.280): Opus 5.5 added. Older builds get claude_code_version_too_old or a disabled "Update to 2.1.280+" row in /model. The stable channel, npm stable tag, and claude-code cask are still on 2.1.267 (#96130).
• Sep 18 (v2.1.277): Fixed update checks erroring every 30 minutes, and claude update hanging with a minimum or maximum version set, when a proxy returns an invalid version. Fixed claude update on WinGet and apk installs reporting "up to date" after a failed version lookup. Failed auto-updates no longer leave large staged downloads in ~/.cache/claude/staging.
• Aug 19 to mid-September: the stable channel sat on 2.1.236 for weeks, so stable apt/dnf/apk and Homebrew users saw no upgrades (#92274). It has since moved to 2.1.267.
• Sep 1 (v2.1.258): Fixed Claude Code failing to launch on macOS 12 Monterey, a regression from 2.1.255.
• Aug 25 (v2.1.245): Fixed a startup crash on distros that ship glibc 2.44 (Arch, CachyOS, Fedora Rawhide).
• Late August (v2.1.243): Native install and auto-update downloads are now zstd-compressed, about 75 MB instead of 340 MB on Linux x64.

Error Lookup Table

Match what your terminal printed to the fix. Each row links to a section below with the full commands.

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 by shell:

Before editing anything, open a new terminal window. The shell you installed from keeps its old PATH, so a fresh window is sometimes the whole fix.

Check whether the install directory is on your PATH:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

No output means it is missing. Add it to your shell config:

# 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 --version

On Windows PowerShell, append the directory to your User PATH and restart the terminal:

$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 needs neither root nor Node.js, and it auto-updates in the background:

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

Do not put sudo in front of the native installer either. The current install.sh checks for it and stops with Error: do not run this installer with sudo. The script installs into $HOME, and under sudo that resolves to root's home, so claude would land in /root/.local/bin and never appear in your own shell. Plain root with no sudo (containers, CI) is not blocked. To install for root on purpose, the script accepts CLAUDE_INSTALL_ALLOW_SUDO=1:

curl -fsSL https://claude.ai/install.sh | sudo CLAUDE_INSTALL_ALLOW_SUDO=1 bash

If the native installer itself hits permission errors, the target directories are not writable by your user. Check and repair 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) ~/.local

If you must stay on npm (corporate mirror, lockfile pinning), note that npm is still a supported install method, not a deprecated one, but the requirements moved. Since v2.1.198 the package declares Node.js 22 or later ("engines": {"node": ">=22.0.0"} on the registry). Older Node prints an EBADENGINE warning and the install still completes, because the package pulls the native binary through per-platform optional dependencies like @anthropic-ai/claude-code-darwin-arm64 and never runs your Node at runtime. Skip those optional dependencies and you get Fix 13. Upgrade with npm install -g @anthropic-ai/claude-code@latest, not npm update -g. Full npm walkthrough: npm install claude code.

On Windows, npm installs can also fail with npm.ps1 cannot be loaded because running scripts is disabled on this system. That is PowerShell's execution policy blocking npm's .ps1 shims. Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser, call npm.cmd instead, or skip npm and use irm https://claude.ai/install.ps1 | iex, which the policy does not affect.

3. "syntax error near unexpected token '<'" (Install Script Returns HTML) and "Failed to fetch version"

Bash tried to execute an HTML page. You will see one of:

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

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

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 it

In PowerShell use curl.exe -sI; PowerShell aliases curl to Invoke-WebRequest, which rejects those flags. A 403 from that check usually means a proxy or network filter is blocking the host (or the region is unsupported); a 5xx is a temporary service issue, so wait a few minutes.

"Failed to fetch version from downloads.claude.ai"

Messages like Failed to fetch version from https://downloads.claude.ai/claude-code-releases/latest after 3 attempt(s): connect ECONNREFUSED come from the installer or the auto-updater, not from your account. The machine cannot open a connection to downloads.claude.ai. ECONNREFUSED or a timeout points at a firewall, a missing HTTPS_PROXY, or a VPN that drops the route. Run the curl -sI check above, then set the proxy variables from Fix 4. The installers print a related message, Failed to get a valid version from downloads.claude.ai (got unexpected content), when a proxy or captive portal answers with its own page instead of the version string.

Two related curl exit codes: curl: (56) Failure writing output to destination means the download was cut off mid-stream, and curl: (23) means bash exited before reading the whole script. Both are usually intermittent. Retry once before changing anything. Since v2.1.202, the installer and updater retry dropped connections instead of failing with "aborted".

If the network is fine and the error persists, use a package manager instead. They install the same binary:

# macOS
brew install --cask claude-code

# Windows
winget install Anthropic.ClaudeCode

4. 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.

# 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.pem

If 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.

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

Windows-specific TLS fixes:

• Old PowerShell defaults: enable TLS 1.2 first with [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12, then irm https://claude.ai/install.ps1 | iex.
• CRYPT_E_NO_REVOCATION_CHECK or CRYPT_E_REVOCATION_OFFLINE: your firewall blocks certificate revocation lookups. Add --ssl-revoke-best-effort to the CMD install command, or use winget install Anthropic.ClaudeCode which 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. That issue was closed as not planned on July 31, 2026, so do not wait for a fix. 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:

wsl --set-version <DistroName> 2

If you must stay on WSL1, invoke the binary through the dynamic linker by adding this function to ~/.bashrc:

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:

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, then npm install -g @anthropic-ai/claude-code --force. No sudo.
• exec: node: not found at 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:

Your prompt tells you which shell you are in: PS C:\Users\you> is PowerShell, C:\Users\you> without the PS is CMD. Neither needs an Administrator window.

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:

{
  "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. The file name matters: Claude Code accepts only bash.exe, sh.exe, bash, or sh. Point it at Git's git-bash.exe launcher and it ignores the variable with a warning, then falls back to auto-detection. Before v2.1.219, a wrong path instead crashed startup with Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path.

Auto-detection checks C:\Program Files\Git, then C:\Program Files (x86)\Git, then the git on your PATH. It skips a git that sits inside the folder you launched from under node_modules or a virtualenv folder like .venv, so a project cannot plant its own shell. If the name and path are right and it still fails, endpoint security (AppLocker, EDR) is the usual cause: 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:

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 global

Keep one. Anthropic recommends the native install at ~/.local/bin/claude (it auto-updates in the background). Remove the others:

# 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.ClaudeCode

Then 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.

One exception worth knowing: in early September 2026, the copy of Claude Code that the Claude Desktop app bundles (v2.1.255) crashed on macOS 12 Monterey with dyld: Symbol not found: (_DNSServiceGetAddrInfoEx) and exit code 134, while the standalone CLI (v2.1.258) ran on the same machines. Reporters in issue #91381 found Desktop kept re-downloading 2.1.255 after cache clears. The CLI fix landed in v2.1.258 on September 1 ("Fixed Claude Code failing to launch on macOS 12 (Monterey), a regression introduced in 2.1.255"). On September 22 a new Monterey report followed: Desktop stays on its bundled 2.1.260, so Opus 5.5 is greyed out there while the standalone CLI runs 2.1.280 (#96105). Monterey is below the documented floor either way, so treat the curl install as a stopgap and plan the macOS upgrade.

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, which Anthropic describes as about a week behind; claude-code@latest tracks latest. On September 22, 2026 the two casks were at 2.1.267 and 2.1.280, and stable spent late August stuck on 2.1.236. If a new model is greyed out on a Homebrew install, check which cask you have first (Opus 5.5 fix). Neither auto-updates by default (you run brew upgrade claude-code), unless you set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 (added in v2.1.129), which makes Claude Code run the brew or winget upgrade in the background. The curl installer auto-updates on its own. Installing both leaves two binaries on PATH and a version that appears to never update (Fix 9). Pick one.

Two Homebrew-specific errors. Error: Cask 'claude-code' is unavailable: No Cask with this name exists means your local cask index predates the cask: run brew update, then install again. Error: Cask 'claude-code' is not installed. during uninstall usually means you installed the other cask; run brew uninstall --cask claude-code@latest. Homebrew also keeps old versions after upgrades, so run brew cleanup now and then.

11. Linux: "Killed" During Install and Alpine Library Errors

Killed mid-install on a VPS means the Linux OOM killer terminated the claude install step. Current versions of install.sh say so directly: Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory. The install step needs roughly 512 MB of free memory, and running Claude Code needs 4 GB+ RAM. On a small instance, add swap:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

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

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

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

On glibc systems (check with ldd --version), the installer may have misdetected musl because cross-compilation packages are present; remove the install and reinstall. A crash at startup on a rolling distro with glibc 2.44 (Arch, CachyOS, Fedora Rawhide) was fixed in v2.1.245, so update to at least that version. 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

The exact text is API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}. Installing is free; running is not. Claude Code requires Pro ($17/mo annual, $20 monthly), Max (from $100/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".

13. "Error: claude native binary not installed" After npm Install

The npm package ships a 500-byte placeholder as claude. A postinstall script swaps it for the real binary, which arrives as a per-platform optional dependency. If npm skips either step, the placeholder stays and prints:

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

Or reinstall without --ignore-scripts / --omit=optional.

On Windows the placeholder is named claude.exe but is really a shell script, so PowerShell reports Program 'claude.exe' failed to run: ... The specified executable is not a valid application for this OS platform. That reads like an architecture problem. It is the same missing binary.

If postinstall can never run in your environment, node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs finds the downloaded platform package and launches it, at the cost of one extra Node process per start.

The placeholder can also appear after a successful-looking update. Issue #95297 (open, September 2026) reports claude upgrade on an nvm-managed npm install printing success while bin/claude.exe stayed the 500-byte stub. The platform package was present. The recoveries are the same as above: run install.cjs by hand, or switch to the native installer.

One more npm-only error: npm error code ENOTEMPTY ... rename during an update or reinstall. An interrupted earlier run left a .claude-code-* temp directory behind. Delete the directory named on the npm error path line plus any .claude-code-* siblings, then reinstall:

rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
npm install -g @anthropic-ai/claude-code

14. "Auto-update failed: claude.exe in Use" and Other Update Failures

The full message is Auto-update failed: claude.exe in use (close other Claude Code sessions, including VS Code). Windows will not let a process overwrite an executable that is running, and that includes the session doing the update. Anyone who keeps one session open all day can see this on every update check. The fix is to close every Claude Code window, including the VS Code extension, then run:

claude update
claude --version

Since v2.1.169 the updater stops retrying for the rest of the session once it sees the lock, and since v2.1.217 a failed Windows update restores the previous claude.exe instead of leaving none. npm-global installs on Windows still have a gap. Issue #90233 (open) documents the updater renaming the running binary to claude.exe.old.<timestamp> and never cleaning it up. That is about 240 MB per failed attempt, in node_modules\@anthropic-ai\claude-code\bin. Sometimes the new binary never lands at all. npm install -g @anthropic-ai/claude-code recovers it, and you can delete the .old files by hand. The result of the last attempt is in ~/.claude/.last-update-result.json. An error_code of update_apply_exe_locked confirms this cause.

If you manage your own rollout, DISABLE_AUTOUPDATER=1 stops background checks but still allows claude update. DISABLE_UPDATES=1 (v2.1.118+) blocks every update path, including manual ones.

Opus 5.5 greyed out: "Update to 2.1.280+" and claude_code_version_too_old

Claude Opus 5.5 shipped on September 22, 2026 with Claude Code v2.1.280, and older builds cannot use it. In /model it shows as a disabled row that reads Update to 2.1.280+ to use Opus 5.5. In the Desktop app the tooltip says Update Claude to use this model on this computer. Forcing it with /model claude-opus-5-5 returns an API error:

API error: 400 ... "Claude Code 2.1.275 does not support this model;
version 2.1.280 or newer is required. Run 'claude update', or update the
Claude desktop app, then try again." ... "error_code":"claude_code_version_too_old"

claude update alone does not fix it for everyone. It updates within your channel, and on September 22 the stable channel, the npm stable tag, and the claude-code Homebrew cask all serve 2.1.267 (issue #96130). Fable 5.1 hit the same wall in September (#91345). Move to the latest channel for your install method:

# Native installer: switch the install to latest
curl -fsSL https://claude.ai/install.sh | bash -s latest
# and in ~/.claude/settings.json: { "autoUpdatesChannel": "latest" }

# Homebrew: the claude-code cask tracks stable
brew uninstall --cask claude-code
brew install --cask claude-code@latest

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

claude --version   # expect 2.1.280 or newer

Signed apt, dnf, and apk installs need the repo's latest channel instead of stable. If you can wait, the stable channel will pick up 2.1.280 in a later promotion.

Two edge cases. If you already run 2.1.280 and the disabled row still appears, an older Claude Code session left open during the auto-update cached the placeholder in ~/.claude.json (#96131). Close the old sessions and start a fresh one. And the Claude Desktop app on macOS 12 stays on its bundled Claude Code 2.1.260, because newer Desktop builds do not install on Monterey (#96105). The standalone CLI on the same Mac updates to 2.1.280 and offers Opus 5.5.

15. Claude Desktop Install Errors: "AddPackage Failed" and the September Windows Update

Some "Claude install failed" reports are about the Claude Desktop app, not the Claude Code CLI. The Windows Desktop app installs as an MSIX package. It can fail with AddPackage failed with HRESULT 0x80073CF9 (also 0x80073CF6, 0x80073CFF, or 0x80073D28) when an earlier install left a CoworkVMService behind that the new package cannot replace. Issue #74170 is still open. The workaround that reporters confirm: back up the app's local state, delete the orphaned CoworkVMService, rerun the installer, and restore the backup.

A separate Desktop problem showed up in September 2026. Windows 11 update KB5124008, released September 8, stopped Cowork from reaching local files. Per Anthropic's Cowork changelog, Claude Code (including the Code tab) was not affected. Microsoft shipped the fix (KB5129195 on 24H2 and 25H2), and Anthropic marked it resolved on September 14. Reinstalling Claude does not help with it.

If you only need Claude Code, you can skip the Desktop installer entirely. irm https://claude.ai/install.ps1 | iex or winget install Anthropic.ClaudeCode installs the CLI to %USERPROFILE%\.local\bin without MSIX or admin rights.

Clean Uninstall and Reinstall

When an install is wedged beyond diagnosis, removing everything and reinstalling takes under a minute:

# 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 | bash

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

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

Installed with a package manager instead? Use its own removal command before reinstalling: brew uninstall --cask claude-code, winget uninstall Anthropic.ClaudeCode, npm uninstall -g @anthropic-ai/claude-code, or sudo apt remove claude-code / sudo dnf remove claude-code / apk del claude-code.

To pin a version instead of reinstalling latest, pass it to the installer: curl -fsSL https://claude.ai/install.sh | bash -s 2.1.267 (the stable build on September 22, 2026), 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

claude --version    # prints the installed version
claude doctor       # full diagnostic: install type, PATH, auth, config
claude update       # applies any pending update immediately

System 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 uses Node.js, and since v2.1.198 it declares Node.js 22 or later (older versions get an EBADENGINE warning, not a failure). 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.

How do I fix "Error: claude native binary not installed"?

npm skipped the platform package (--omit=optional, optional=false) or the postinstall step (--ignore-scripts). Reinstall without those flags, or run node node_modules/@anthropic-ai/claude-code/install.cjs if only scripts were skipped. The native installer avoids the problem entirely. Details in Fix 13.

What does "Auto-update failed: claude.exe in use" mean?

A running session, possibly inside VS Code, holds the executable, and Windows will not let it be overwritten. Close every session and run claude update. After failed npm-global updates, delete leftover claude.exe.old.* files of about 240 MB each. See Fix 14.

Why does the Claude Code installer say "do not run this installer with sudo"?

Under sudo, $HOME points at root's home, so claude would install where your own shell never looks. Rerun the command without sudo. Set CLAUDE_INSTALL_ALLOW_SUDO=1 only if you want a root-owned copy.

Does Claude Code work on WSL1?

WSL1 hits a known Exec format error regression (issue #38788, closed as not planned in July 2026) 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 is Opus 5.5 greyed out in Claude Code?

Opus 5.5 needs Claude Code 2.1.280 or newer. On September 22, 2026 the stable channel, the npm stable tag, and the claude-code Homebrew cask were on 2.1.267, so those installs show Update to 2.1.280+ to use Opus 5.5 or fail with claude_code_version_too_old. Switch to the latest channel: curl -fsSL https://claude.ai/install.sh | bash -s latest, brew install --cask claude-code@latest, or npm install -g @anthropic-ai/claude-code@latest. See Fix 14.

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 (from $100/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.

Is Claude Code supported on Windows?

Yes. Native Windows needs Windows 10 1809+ or Server 2019+ on a 64-bit OS, no admin rights, and PowerShell or Git for Windows. Install with irm https://claude.ai/install.ps1 | iex or winget install Anthropic.ClaudeCode. WSL2 also works and is the only Windows option with sandboxing support.