Claude Code Installation Failed: Fix It Fast

The symptom you are seeing

You ran the install, and instead of a working claude command you got one of these: an npm ERR! code EACCES permissions wall, a clean install that finishes but then claude: command not found, an npm ERR! engine complaint about your Node version, a network timeout or ETIMEDOUT behind a corporate firewall, or a confusing path error inside WSL or Windows. The install "failed" is a single phrase covering several distinct problems, and the fix depends on which one you actually hit.

This page is triage. Each section below is a real cause, the error text that points to it, and the exact command that fixes it. Work through them in order; the first two cover the large majority of cases. Once claude runs, the Claude Code setup guide covers configuring it properly, and if it installs but then misbehaves, why Claude Code is not working covers post-install issues.

Throughout, the canonical install command is the npm global install:

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

If that command is what failed, read on.

Cause 1: npm global permission error (EACCES)

This is the most common failure on macOS and Linux. The error looks like:

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/@anthropic-ai
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/...'

The cause: your npm is configured to install global packages into a system directory (/usr/local/lib or similar) that your user account does not own, so the install cannot write there.

The wrong fix is sudo npm install -g. It works once, but it installs packages as root, which causes a cascade of permission problems later and is a genuine security risk. Do not do this.

The right fix is to point npm's global prefix at a directory you own:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

Then add that directory's bin to your PATH by appending this line to your shell profile (~/.zshrc for zsh, ~/.bashrc for bash):

export PATH=~/.npm-global/bin:$PATH

Reload the shell (open a new terminal, or source ~/.zshrc), then install again without sudo:

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

This is a one-time fix that makes every future global install work without elevation. If you use a Node version manager (see Cause 3), you usually do not hit this at all, because those managers install Node into your home directory.

Cause 2: installed successfully but command not found

The install completed with no errors, but running claude gives:

claude: command not found

The cause: the directory npm installed the binary into is not on your PATH, so your shell cannot find it. The package is on disk; the shell just does not know where to look.

First, find where npm put it:

npm config get prefix

The binary lives in the bin subdirectory of whatever that prints (for example, if it prints /Users/you/.npm-global, the binary is at /Users/you/.npm-global/bin/claude). Confirm it is there:

ls $(npm config get prefix)/bin/claude

If that file exists, the fix is to add that bin directory to your PATH. Append to your shell profile:

export PATH="$(npm config get prefix)/bin:$PATH"

Open a new terminal and run claude again. If ls showed no file, the install did not actually complete; rerun the install (and check Cause 1 for permission errors that may have aborted it silently).

A frequent variant: the install worked in one shell but command not found appears in another, because you added the PATH line to ~/.bashrc but your terminal uses zsh (the default on modern macOS). Add the line to the profile your shell actually reads. Run echo $SHELL to confirm which shell you are in.

Cause 3: unsupported Node.js version

The install aborts with an engine warning:

npm ERR! code EBADENGINE
npm ERR! engine Unsupported engine
npm ERR! notsup Required: {"node":">=18.0.0"}
npm ERR! notsup Actual:   {"node":"v16.20.0"}

The cause: Claude Code requires a current Node.js LTS version, and you are on an older one. Check yours:

node --version

If it is below the required version, upgrade. The cleanest way is a version manager, which also sidesteps the permission problem from Cause 1. Install nvm and a current LTS:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# open a new terminal, then:
nvm install --lts
nvm use --lts

Confirm the new version, then install Claude Code:

node --version
npm install -g @anthropic-ai/claude-code

If you installed Node through your system package manager (apt, Homebrew) and it is stuck on an old version, a version manager is still the better long-term answer because it lets you switch versions per project without fighting the system package.

Cause 4: corporate proxy or blocked registry

The install hangs and then times out, or fails to reach the registry:

npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/... failed
npm ERR! network This is a problem related to network connectivity.

The cause: you are behind a corporate firewall or proxy that blocks or intercepts the connection to the npm registry. This is common on managed work machines.

First confirm it is the network and not something local by testing registry reachability:

npm ping

If that fails, configure npm to use your organisation's proxy. Get the proxy URL from your IT team, then:

npm config set proxy http://proxy.yourcompany.com:8080
npm config set https-proxy http://proxy.yourcompany.com:8080

If your company runs an internal npm registry or mirror (Artifactory, Nexus, Verdaccio), point npm at it instead:

npm config set registry https://npm.yourcompany.com/

Some corporate proxies also break TLS by injecting their own certificate. If you see a SELF_SIGNED_CERT_IN_CHAIN or UNABLE_TO_GET_ISSUER_CERT_LOCALLY error, the correct fix is to add your company's root CA to Node's trusted certificates via the NODE_EXTRA_CA_CERTS environment variable pointing at the company CA file. Do not disable certificate checking globally with strict-ssl false; that turns off TLS verification for every package you ever install and is a real security exposure.

Cause 5: WSL and Windows path problems

On Windows, the cleanest setup runs Claude Code inside WSL (Windows Subsystem for Linux). Problems here usually come from crossing the Windows/Linux boundary, with errors like a binary that will not execute, garbled paths, or command not found despite a successful install.

The most common mistake is installing Node for Windows and then trying to use it from inside WSL, or the reverse. They are separate environments with separate PATHs. The fix is to install Node and Claude Code entirely inside WSL:

# inside the WSL (Ubuntu) terminal, not Windows PowerShell
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# open a new WSL terminal, then:
nvm install --lts
npm install -g @anthropic-ai/claude-code

A second WSL trap is working on files mounted from the Windows side (paths under /mnt/c/...). File access across that boundary is slow and the permission model differs, which can cause odd failures. Keep your projects inside the WSL filesystem (under your Linux home directory) rather than under /mnt/c/.

If you are determined to run natively on Windows without WSL, make sure you are using a current Node LTS for Windows and running the install from a fresh terminal so the PATH is up to date, but WSL remains the smoother path for most people.

Cause 6: a half-finished or corrupted install

Sometimes a previous attempt failed partway (a permission error mid-install, a dropped connection) and left a broken package behind. Now reinstalling produces strange errors, or claude exists but crashes on launch.

The fix is to remove the package cleanly and reinstall:

npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code

npm cache clean --force clears cached package data that may be corrupt. If the uninstall itself errors because files are missing, you can also delete the package directory directly from your global node_modules (under $(npm config get prefix)/lib/node_modules/@anthropic-ai/) and then reinstall.

If the install succeeds but the very first run fails to authenticate or behaves oddly rather than failing to install, that is a different class of problem; why Claude Code is not working covers post-install and runtime issues.

Prevention: a setup that does not break

Most installation failures trace back to two root choices, and fixing those once prevents the whole category.

Use a Node version manager instead of a system or sudo install. Installing Node through nvm (or fnm, or Volta) puts Node and your global packages inside your home directory, which eliminates the EACCES permission errors from Cause 1 entirely, makes upgrading Node a single command when you hit Cause 3, and keeps everything in a PATH you control. This single decision removes the two most common failure modes.

Verify the install with a quick check before relying on it. After installing, confirm the version and location so you catch a PATH problem immediately rather than mid-task:

claude --version
which claude

If both succeed, you are set. If which claude prints nothing, you have the Cause 2 PATH problem and can fix it now rather than later.

For teams, a short note in onboarding docs saying "install Node via nvm, then npm install -g @anthropic-ai/claude-code, then verify with claude --version" prevents most new starters from hitting any of this. Once Claude Code runs, putting a CLAUDE.md memory file in each project gives the agent its constraints from the first session.

When to escalate

Work through the causes above in order before escalating, because the first two resolve the large majority of failures. Escalate beyond self-service when:

• You have ruled out permissions (Cause 1), PATH (Cause 2), and Node version (Cause 3), and the install still fails with an unfamiliar error. Capture the full output of the failing command, including the lines above and below the error, before asking for help.
• The failure is clearly a corporate-network issue (Cause 4) that needs IT to provide the proxy URL, internal registry address, or root CA file. This is not something you can fix alone on a locked-down machine.
• The error references a problem inside the package itself rather than your environment (a missing file the package should ship, a version mismatch in its own dependencies). Note your operating system, Node version (node --version), and npm version (npm --version), and report it with the full error text so it can be diagnosed against a known platform.

When you do escalate, the three facts that make diagnosis fast are your OS, your node --version, and the complete error output. With those, almost any failed Claude Code install can be matched to one of the causes above.

Get Claudify. A clean Claude Code setup with the CLAUDE.md templates and permission rules that make the agent productive the moment installation succeeds.