Claude Code "command not found: claude": Install and PATH Error Fixes

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

zsh: command not found: claude                                         # macOS
bash: claude: command not found                                        # Linux
'claude' is not recognized as an internal or external command         # Windows CMD
claude : The term 'claude' is not recognized as the name of a cmdlet   # PowerShell

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 — checked against the official docs as of September 29, 2026.

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.

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 install methods listed on the official setup page as of September 29, 2026, and where the binary lands (the native installer is recommended).

The point: the native installer is officially recommended. The npm version installs the same native binary. Since v2.1.198 the npm package requires Node.js 22 or later, but on an older Node.js npm only prints an EBADENGINE warning and the install still completes (the binary doesn't use Node at runtime). The npm route is more prone to permission and PATH trouble, so 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.

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; for bash on macOS, use ~/.bash_profile (Terminal starts bash as a login shell, which ignores ~/.bashrc). In Windows PowerShell, add it to your User PATH with [Environment]::SetEnvironmentVariable('PATH', "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$env:USERPROFILE\.local\bin", 'User'). After the change, open a new terminal and confirm with claude --version.

"Native installation exists but ~/.local/bin is not in your PATH"

This warning appears in the claude doctor output (under "Installation warnings") and below the input prompt. As users have quoted it in the official GitHub issues, it reads:

Native installation exists but ~/.local/bin is not in your PATH
Run: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc then open a new terminal or run: source ~/.zshrc

It means the native binary is in ~/.local/bin, but that folder is not in the PATH Claude Code sees. The fix is the one above: add the line to your shell's config file and open a new terminal. If echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin" already prints the folder in a new terminal and the warning still appears, you are in a case reported on GitHub (#63695: PATH set only in ~/.zshenv and launched from the VS Code terminal; #75431: claude installed somewhere else). Both were closed without a fix as of September 29, 2026. If claude --version works in a new terminal, the install itself is fine.

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.

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) Git for Windows is optional: without it Claude Code runs commands through its PowerShell tool. If Git is installed but Claude Code can't find Git Bash, point CLAUDE_CODE_GIT_BASH_PATH in settings at your bash.exe. Running under WSL is also an option.

VS Code: "Could not locate the Claude CLI on PATH"

The VS Code extension shows this on Windows when you open Claude Code in the integrated terminal, the terminal's shell is PowerShell, and the extension can't find the installed claude on PATH. The message starts like this:

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH.

The extension blocks the launch because running claude by name in PowerShell could pick up a claude in the open folder instead of the installed CLI. (1) Open a new PowerShell window outside VS Code and run where.exe claude; if it prints nothing, add the install folder to PATH as in §3. (2) Put the PATH entry in the user or system environment variable, not only in your PowerShell profile (the extension doesn't run your profile). (3) Restart VS Code, because it reads PATH only at startup.

"'claude' is not recognized" right after an update

To update on Windows, Claude Code renames the existing claude.exe to a backup named claude.exe.old. plus a timestamp and moves the new version into place. If that move fails and the rename can't be undone, %USERPROFILE%\.local\bin is left with the backup but no claude.exe. Restore the newest backup in PowerShell:

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

Then confirm with claude --version. If there is no claude.exe.old.* file, reinstall with irm https://claude.ai/install.ps1 | iex. Since v2.1.281 a failed update restores the preserved executable automatically.

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 result of the most recent update attempt with claude doctor. Homebrew, WinGet, apt, dnf, and apk installs don't auto-update by default; on Homebrew and WinGet, setting CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 makes Claude Code run the upgrade for you.

"Auto-update failed · Run claude doctor"

When a background update attempt fails, a running session shows this in its status area. GitHub issues quote two forms: Auto-update failed · Run claude doctor (v2.1.220 to v2.1.278) and, on npm installs of earlier versions, Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code. Handle it in this order:

1. Run claude doctor in a terminal — it shows the result of the most recent update attempt and any installation warnings.
2. Run claude update to apply the update now. It reports Successfully updated from <old version> to version <new version>, or Claude Code is up to date (<version>) if nothing is pending.
3. If you're already up to date, the failure was temporary (for example, a dropped network connection). GitHub issues (#89286, #96038) report that the notice can stay until you restart the session.
4. On an npm global install whose folder isn't writable, auto-update can't work — migrate to the native installer (see the box above).
5. If it keeps failing on a company network, check that downloads.claude.ai is reachable.

6. The diagnostic workflow

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

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 wants Node.js 22+ 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 you see Auto-update failed · Run claude doctor, run claude doctor and then claude update; if it says you're up to date, restarting the session clears the notice. 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.