Claude Code Command Not Found: Fix PATH, Install, and Shell Issues

Overview

Claude Code command not found means the terminal cannot resolve the Claude Code executable from the current shell environment. The problem is usually local: Claude Code is not installed, the install completed into a directory that is not on PATH, the terminal session has not reloaded shell configuration, or multiple Node/npm installations are pointing at different global binary directories. Anthropic documents Claude Code as a terminal-based coding tool in Claude Code official documentation. This fix focuses on the CLI path from command lookup to reinstall, not account billing, real-time service status, or unsupported version claims.

Symptoms

The failure appears before Claude Code starts. You type claude in a terminal, and the shell reports that the command cannot be found or is not recognized. On Unix-like shells, this usually means no executable named claude was found in any directory listed in PATH. On Windows, the equivalent issue can appear in PowerShell, Command Prompt, Git Bash, or WSL depending on where Node and npm installed the executable. If the CLI opens but authentication, model access, or project analysis fails afterward, that is a different troubleshooting path.

claude
# shell reports a command-not-found or not-recognized error

Why This Happens

Command lookup is mechanical. The shell searches each directory in PATH from left to right and runs the first matching executable. Claude Code can be correctly installed but invisible if npm placed its binary in a directory such as a user npm prefix, an nvm-managed Node directory, or a package-manager-specific location that your shell does not load. The same machine can have several terminal environments with different startup files. zsh, bash, fish, PowerShell, WSL, and IDE-integrated terminals may not share the same PATH, even when they show the same home directory.

Quick Diagnostic Commands

Start with read-only checks. These commands do not install or remove anything; they only show what your shell can resolve. If command -v claude prints nothing, the shell cannot see the executable. If npm is missing, the install path is not available from that terminal. If npm exists but its global bin directory is absent from PATH, fix the shell profile rather than reinstalling repeatedly. Anthropic’s package is published as @anthropic-ai/claude-code on npm.

command -v claude
node --version
npm --version
npm prefix -g
printf '%s\n' "$PATH" | tr ':' '\n'

$ command -v claude
# no output means the shell did not find the executable
$ npm prefix -g
# compare this prefix with directories listed in PATH

Install or Reinstall Claude Code

If claude is missing and npm is available, install Claude Code using the official npm package name. The command below installs the package globally for the npm environment currently active in the terminal. That detail matters: if you use nvm, fnm, Volta, asdf, Homebrew Node, or system Node, each may have a different global package location. After installing, open a new terminal and run command -v claude again. Do not mark the install fixed until the command resolves from the same shell where you plan to work.

npm install -g @anthropic-ai/claude-code
command -v claude
claude --help

Fix PATH for npm Global Binaries

When npm installs the package but claude still cannot be found, locate npm’s global prefix and add the matching binary directory to your shell startup file. On many Unix-like systems, the binary directory is the bin folder under npm prefix -g. With nvm or similar tools, the path may include the active Node version. Add the path only once, then restart the terminal. Avoid adding stale paths from old Node versions because they can cause the shell to run outdated or broken binaries before the current one.

npm prefix -g
# Example shape only: /home/user/.npm-global
# Add the corresponding bin directory to PATH in your shell profile.

zsh, bash, and fish Shell Checks

Shell startup files are a common gotcha. macOS terminals often use zsh and load ~/.zshrc for interactive sessions. Many Linux systems use bash and load ~/.bashrc. fish uses a different configuration path and syntax. If you add a PATH export to the wrong file, new terminals will still fail. Check the active shell with echo $SHELL, then edit the matching config. For zsh and bash, keep the npm bin path before system paths only when you intentionally want that Node environment to take priority.

echo "$SHELL"
# zsh:  edit ~/.zshrc
# bash: edit ~/.bashrc
# fish: edit ~/.config/fish/config.fish

macOS and Homebrew Node Gotchas

On macOS, the most common split is between Homebrew Node, nvm-managed Node, and an IDE terminal inheriting a reduced environment. Apple Silicon Homebrew commonly lives under /opt/homebrew, while Intel Homebrew commonly uses /usr/local. Do not hard-code either path without checking your machine. Run which node, which npm, and npm prefix -g in the same terminal. If Claude Code works in Terminal but not inside VS Code, compare the integrated terminal environment; VS Code documents terminal behavior in Visual Studio Code terminal documentation.

Linux and WSL Checks

On Linux and WSL, the issue is often a mismatch between system Node, user-installed Node, and shell initialization. WSL adds another boundary: Windows npm globals are not the same as Linux npm globals inside WSL. Install and run Claude Code inside the environment where you plan to use it. If you work in WSL, run node, npm, and claude from the WSL shell, not from Windows PowerShell. If permissions block global installs, prefer a user-owned Node manager or npm prefix over changing ownership of broad system directories.

which node
which npm
npm prefix -g
ls -la "$(npm prefix -g)"

Windows PowerShell Checks

On Windows, first confirm whether you are using PowerShell, Command Prompt, Git Bash, or WSL. Each can resolve commands differently. If npm installed a command shim, the npm global directory must be on the Windows user or system PATH. Restart PowerShell after changing environment variables; existing windows do not always pick up updates. If claude works in WSL but not PowerShell, that is expected when the package was installed only inside WSL. Choose one environment for the project and keep the install there.

Permission Problems After Global Install

Permission errors can produce a partial install where npm reports activity but no usable claude command appears. The risky fix is to rerun the command with sudo; the better fix is to make the npm global location user-owned or use a Node version manager that keeps packages under your home directory. Check ownership before changing anything. Do not recursively change ownership of /usr, /usr/local, or other broad system trees without understanding the package manager impact.

npm prefix -g
ls -ld "$(npm prefix -g)"
# If this directory is root-owned, use a user-managed Node setup or npm prefix.

When Not to Reinstall

Reinstalling is not useful when the command exists but a later Claude Code flow fails. If command -v claude returns a path and claude --help displays help, the command-not-found issue is resolved. Next failures may involve login, network policy, project permissions, shell working directory, or feature availability. Separate those errors by capturing the exact command, terminal type, current directory, Node/npm versions, and the full message shown after the CLI starts. That record is more useful than deleting packages and changing PATH repeatedly.

If It Still Fails

If the command still cannot be found after install and PATH checks, reduce the environment. Open a fresh terminal, run node --version, npm --version, npm prefix -g, and command -v claude, then compare the outputs across your normal terminal and a second terminal app. If one works, copy the working environment’s PATH logic into the failing shell profile. If none work, reinstall from the official package source and capture the full npm output. For account or product behavior after the command launches, use Anthropic’s official support route rather than treating it as a shell issue.

FAQ

Why does Claude Code say command not found after installing?

The package may have installed into an npm global binary directory that your shell does not search. Run npm prefix -g and compare the related bin directory with the directories in PATH. Restart the terminal after changing shell configuration.

What command should I run first?

Run command -v claude on macOS, Linux, or WSL. It shows whether the current shell can resolve the executable. If it prints nothing, troubleshoot install location and PATH before checking account or model access.

Should I use sudo to install Claude Code globally?

Avoid sudo as the default fix. It can create root-owned npm files and cause future installs or updates to fail. Prefer a user-managed Node installation, a corrected npm prefix, or a properly configured Node version manager.

Why does Claude Code work in one terminal but not another?

Different terminals can load different startup files and environment variables. Terminal.app, VS Code, zsh, bash, fish, PowerShell, and WSL may each have a different PATH. Run the same lookup commands in each environment and align the failing one.

Is this caused by a Claude outage?

A command-not-found error happens before the Claude Code CLI starts, so it is usually a local shell or installation issue. Do not treat it as an outage unless the CLI launches and then reports a service-side error.

How do I know the command-not-found issue is fixed?

The issue is fixed when command -v claude returns a path and claude --help runs from the terminal you use for development. Any later login, permission, or project error should be handled separately.