Install Troubleshooter

Why Claude Code installs fail

Almost every failed Claude Code install traces back to one of five things: the binary is not on your PATH, npm hit a permission wall installing globally, your Node version is too old, a proxy or firewall blocked the download, or the install stalled on a flaky network. Pick your OS and symptom above and this troubleshooter gives you the ordered fix for that exact combination. The commands are tailored per operating system because the right fix on macOS is not the right fix on Windows.

Work the steps in order and stop when it works - you rarely need all of them. The first step for most symptoms is a cheap check (run `claude --version`, run `node --version`) that tells you whether the problem is even what you think it is.

The five install failure modes

• PATH - the binary installed but the shell cannot find it. The most common 'command not found' cause. Fix: add the global bin folder to PATH and open a new terminal.
• npm permissions (EACCES) - npm cannot write to its global folder. Fix: set a user-owned prefix. Never sudo, never chmod 777.
• Node version - your runtime is older than Claude Code supports. Fix: upgrade Node to current LTS and reinstall.
• Proxy / network - a corporate proxy, VPN, or firewall blocks the download. Fix: set proxy env vars and whitelist the endpoints.
• Stalled install - partial download or corrupted cache. Fix: clear the npm cache and retry with --verbose to see the real blocker.

The safe way to fix npm permission errors

1. Never run `sudo npm install -g`. It plants root-owned files in your npm folder that cause the same EACCES error next time - it moves the problem, it does not solve it.
2. Instead, give npm a global folder your user owns: `mkdir -p ~/.npm-global` then `npm config set prefix ~/.npm-global`.
3. Add that folder's bin to your PATH in your shell profile.
4. Open a new terminal and reinstall without sudo.
5. If a previous sudo install already left root-owned files, the Permission Error Fixer tool on this site walks through reclaiming ownership safely.

Verifying a clean install

Once the install completes, confirm it end to end before you start working. Run `claude --version` to prove the binary is on your PATH. Run `which claude` on macOS/Linux or `where claude` on Windows to see exactly which binary the shell will use - useful if you have multiple Node versions and suspect the wrong one is winning. Then start Claude Code and complete the auth flow. If all three work, the install is genuinely done, not just half-done.

When to reinstall vs when not to

Reinstalling is the right fix for exactly one situation: the binary is actually missing or corrupt (`claude --version` itself errors). For PATH problems, permission problems, Node-version problems, and network problems, a reinstall changes nothing - the new install lands in the same wrong place, hits the same permission wall, or fails on the same old Node. Diagnose the symptom first. Reinstalling as a reflex is how a five-minute PATH fix turns into a lost afternoon.

Getting unstuck for good

Once your environment is set up correctly - a user-owned npm prefix, a current Node, the bin folder on PATH - install and upgrade problems mostly disappear. The one-time investment of fixing the environment properly (rather than sudo-ing past each error) pays back every time you install or update a global tool, not just Claude Code. The Claude Code Club setup module walks through a clean, resilient environment from scratch so you never fight the installer again.