Table of Contents

You installed Claude Code, but typing claude in the terminal gives this — sound familiar?

zsh: command not found: claude
bash: claude: command not found
'claude' is not recognized as an internal or external command   # Windows

This error means "the claude executable cannot be found," and the cause is usually "the install folder is not on your PATH." The install itself often succeeded — the shell just doesn't know where to look. This article covers install methods and locations, how to fix PATH, conflicts between multiple installs, Windows-specific traps, and updating — based on official information.

Key points up front. (1) command not found is almost always just "~/.local/bin (the install dir) is not on PATH" — add it and restart the terminal and it works. (2) An npm permission error (EACCES) should NOT be fixed with sudo — switch to the native installer instead. (3) When stuck, run claude doctor — it checks install health, settings, and the update result together. Exact commands and defaults change by version, so confirm the latest in the official docs.

CLAUDE CODE · PATH

Installed, yet not found

— the install dir just isn't on PATH

$ claude
zsh: command not found: claude
$ echo $PATH shows…
/usr/local/bin : /usr/bin : /bin ← no ~/.local/bin
$ ls ~/.local/bin/claude
~/.local/bin/claude ← the binary is right here!
→ add ~/.local/bin to PATH and restart the terminal

The binary does exist. The shell's PATH just doesn't list its location.
So the fix is "add one line to PATH" — usually under a minute.

1. What this error is telling you

When you type a command, the shell (zsh / bash / PowerShell) searches the folders listed in the PATH environment variable in order and runs the first matching executable. command not found: claude means none of those folders contained claude.

The important thing: it does not necessarily mean the install failed. The native installer places claude in ~/.local/bin (Windows: %USERPROFILE%\.local\bin), but if that folder is not on PATH, the binary exists yet the shell can't find it. So most cases are fixed by "add one line to PATH and restart the terminal." Before suspecting a failed install, run ls ~/.local/bin/claude to check whether the binary is there.

On Windows, a "wrong shell" for the install command (e.g., running the PowerShell command in CMD) produces different errors — covered in §4. First, let's nail down the correct install methods and locations.

2. Install methods and where the binary lives

Here are the main install methods as of 2026 and where the binary lands (the native installer is recommended).

MethodCommand (shape)Location / note
Native (recommended) mac/Linuxcurl -fsSL https://claude.ai/install.sh | bash~/.local/bin/claude. Auto-updates
Native (recommended) WindowsIn PowerShell: irm https://claude.ai/install.ps1 | iex%USERPROFILE%\.local\bin\claude.exe
npmnpm install -g @anthropic-ai/claude-codeNeeds Node 18+. Installs the same native binary
Homebrew (mac)brew install --cask claude-codeNo auto-update → brew upgrade
WinGet (Windows)winget install Anthropic.ClaudeCodeNo auto-update → winget upgrade

The point: the native installer is officially recommended. The npm version installs the same native binary (Node 18+ is needed only at install time; the binary doesn't need Node to run), but it is more prone to permission and PATH trouble. If you're installing fresh, native is the safe choice. Note that installing only the VS Code extension bundles a private CLI inside the extension and does NOT add claude to PATH — if you want claude in the terminal, install it separately.

3. Main causes and fixes

Here are the common causes around command not found, paired with fixes.

ROOT CAUSES

Main install / PATH drivers

1) Not on PATH (most common)
~/.local/bin is off PATH. Add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc/~/.bashrc and restart the terminal.
2) npm permission error (EACCES)
Do NOT sudo npm (officially discouraged). Switching to the native installer is the fastest and safest fix.
3) Node too old (npm method)
The npm method needs Node 18+. Update Node, or use the Node-free native install.
4) Multiple installs conflict
npm + native + Homebrew mixed. Check with which -a claude (Win: where.exe claude) and keep just the native one.
5) Native binary not found (npm)
Could not find native binary package ... appears when you installed with optional deps skipped. Reinstall without --omit=optional etc.

When in doubt, "reinstall via the native installer" resolves most of these —
it sidesteps permission, Node, and conflict problems at once.

A concrete PATH fix (macOS zsh): echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc then source ~/.zshrc. On Linux bash, do the same in ~/.bashrc. After the change, open a new terminal.

4. Windows-specific traps

On Windows, the classic failure is running the install command in the "wrong shell." The error tells you which mix-up happened.

Spotting the wrong-shell mix-up

ErrorMeaning and fix
'irm' is not recognized ...Ran the PowerShell command in CMD → use PowerShell: irm ... | iex
The token '&&' is not validRan the CMD command in PowerShell → use the CMD command
'bash' is not recognized ...Ran the Linux installer on Windows → use the PowerShell installer

Other Windows notes: (1) Restart the terminal after install (a PATH change takes effect in a new terminal). (2) An old Claude Desktop that registered WindowsApps\Claude.exe can make claude launch the desktop app instead of the CLI — update Claude Desktop. (3) If Git Bash isn't found, point CLAUDE_CODE_GIT_BASH_PATH in settings at your bash.exe. Running under WSL is also an option.

5. Auto-update and updating

Native installs auto-update in the background and take effect on next launch. To update manually use claude update; to reinstall/pin a specific version use claude install <version> (also accepts stable / latest). Check the update result with claude doctor.

When auto-update fails on the npm install

If the npm global folder is not writable, auto-update fails. claude doctor lists the fixes, and the root solution is to migrate to a native install. To merely stop auto-update, set DISABLE_AUTOUPDATER in settings env (manual updates still work); to block all updates, set DISABLE_UPDATES.

6. The diagnostic workflow

When the cause is unclear, go top-down. Most cases resolve by step 3.

DIAGNOSE

Isolate it top-down

1
claude doctor (from the shell if it won't start) to check install health.
2
which -a claude / where.exe claude to see where and how many are installed (conflicts?).
3
If the binary exists but isn't found, add ~/.local/bin to PATH and restart the terminal.
4
If they conflict, remove the extra versions (npm/Homebrew/WinGet) and keep one native.
5
Still failing? Reinstall via the native installer (sidesteps permission/Node/conflict).

The rule: "does the binary exist → is it on PATH → is there a conflict?" in that order.
When stuck, a native reinstall is the reliable last resort.

Summary

Claude Code's "command not found: claude" is, in most cases, just "the install dir (~/.local/bin) is not on PATH." The binary exists, so add one line to PATH and restart the terminal and it works. For installing, the native installer is recommended (the npm version needs Node 18+ and has more permission/PATH traps). An npm EACCES should be fixed by switching to native, not sudo.

Diagnose by (1) claude doctor -> (2) which -a claude / where.exe claude for conflicts -> (3) add ~/.local/bin to PATH -> (4) remove extra versions -> (5) native reinstall. On Windows, watch for the wrong-shell mix-up (e.g., irm in CMD), the need to restart the terminal, and the old Claude Desktop Claude.exe conflict. Update with claude update / claude install, and stop auto-update with DISABLE_AUTOUPDATER. When stuck, a native reinstall is the reliable fix. Related: Claude Code error roundup, auth / login errors.

FAQ

Q. I installed it, but I get command not found: claude.
A. Almost certainly the install dir is not on your PATH. First check whether the binary exists with ls ~/.local/bin/claude (Windows: %USERPROFILE%\.local\bin); if it's there, add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc/~/.bashrc and open a new terminal. The install itself usually succeeded.

Q. npm install -g fails with a permission error (EACCES).
A. Do not use sudo npm (officially discouraged; it invites permission and security problems). The fastest, safest path is to switch to the native installer (mac/Linux: curl -fsSL https://claude.ai/install.sh | bash). The native build has no permission traps and needs no Node. You can also move the npm global prefix to a user-writable dir, but the official recommendation is native.

Q. I have multiple claude installs and an old version runs.
A. Run which -a claude (Windows: where.exe claude) to see every claude on PATH. You may have npm-global, Homebrew, WinGet, and native mixed. Keep the native one (~/.local/bin) and remove the others (e.g., npm uninstall -g @anthropic-ai/claude-code) to get down to a single install.

Q. On Windows, typing claude opens the desktop app.
A. An old Claude Desktop registered WindowsApps\Claude.exe, and it takes PATH priority over the CLI. Update Claude Desktop to resolve it. Also, if it's not found or shows an old version after running the PowerShell installer, restart the terminal so the PATH change takes effect.

Q. Updates aren't working / I want to stop them.
A. Native installs auto-update in the background and take effect on next launch. Manually, use claude update; to reinstall/pin, claude install <version>. If auto-update fails on an npm global install, it's a write-permission issue — follow claude doctor and migrate to native. To stop auto-update, set DISABLE_AUTOUPDATER in settings env; to block all updates, set DISABLE_UPDATES.