# Claude Code Command Not Found? 12 Causes and Fixes

> **30-second test:** open a brand-new terminal window and run `claude --version`. If it prints something like `2.1.211 (Claude Code)`, you're done and the old window just had a stale PATH (cause 2). If it still says not found, run `ls -la ~/.local/bin/claude` (Windows PowerShell: `Test-Path "$env:USERPROFILE\.local\bin\claude.exe"`). A file there means a PATH problem: start at cause 1. No file means Claude Code never installed: start at cause 6.

The native installer puts `claude` at `~/.local/bin/claude` on macOS and Linux and at `%USERPROFILE%\.local\bin\claude.exe` on Windows. Your shell only finds programs in folders listed in `PATH`, so most "command not found" problems are that folder missing from `PATH`, a terminal that hasn't picked up the change, or an install that quietly didn't finish.

The error looks different on each platform, but it's the same problem:

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

## Installed, but the shell can't find it: 5 causes

1. **`~/.local/bin` isn't in your PATH.** The installer tells you so under `Setup notes:` with `Native installation exists but ~/.local/bin is not in your PATH.`, but it doesn't change PATH for you. Check with `echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"`. No output means it's missing. Fix for Zsh (the macOS default): `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc` then `source ~/.zshrc`. For Bash on Linux: the same two lines with `~/.bashrc`. For Bash on macOS: use `~/.bash_profile`, because Terminal starts Bash as a login shell that ignores `~/.bashrc` (if you already have `~/.bash_login` or `~/.profile` and no `~/.bash_profile`, put the line there instead). On Windows PowerShell: `$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')` then `[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')`, and restart the terminal. In CMD, add `%USERPROFILE%\.local\bin` to your User PATH in Environment Variables.
2. **The terminal is older than the fix.** A window that was already open keeps its old PATH, and a terminal inside VS Code, Cursor or JetBrains takes its PATH from the editor. Open a new window, or quit and reopen the whole editor, not just its terminal panel. This is also why `claude` isn't found right after a Homebrew, WinGet or PowerShell install: the session you installed from still has the old PATH.
3. **The PATH line never got saved, or went to the wrong file.** Run `grep -n '.local/bin' ~/.zshrc` (use your shell's file). No output means the line isn't there: run the two commands again. Run `echo $0` to see which shell you're actually in; adding the line to `~/.bashrc` does nothing if you use Zsh. If the `echo` printed `zsh: permission denied: /Users/you/.zshrc` or `bash: /home/you/.bashrc: Permission denied`, nothing was saved: check the owner with `ls -l ~/.zshrc`, then `sudo chown $(whoami) ~/.zshrc` if it's owned by `root`, or `chmod u+w ~/.zshrc` if it's yours but read-only. Fish and Nushell users need their own shell's PATH syntax.
4. **You only installed the VS Code extension.** The extension bundles a private copy of the CLI for its own chat panel and doesn't add it to PATH, so `~/.local/bin/claude` won't exist. To use `claude` in a terminal, run the standalone install too: `curl -fsSL https://claude.ai/install.sh | bash` on macOS, Linux and WSL, or `irm https://claude.ai/install.ps1 | iex` in PowerShell.
5. **Windows: `claude.exe` vanished right after an update.** To update, Claude Code renames `claude.exe` to a backup and moves the new one in. If that move fails, the folder can be left with only a file named `claude.exe.old.<timestamp>`. Restore it in PowerShell with `Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe`, then run `claude --version`. If there's no backup, rerun `irm https://claude.ai/install.ps1 | iex`. A related Windows case: an older Claude Desktop can register a `Claude.exe` in `WindowsApps` that wins on PATH, so typing `claude` opens the Desktop app. Update Claude Desktop.

## It never actually installed: 4 causes

6. **You ran the install command for the wrong shell.** `'irm' is not recognized` means you're in CMD: open PowerShell, or use the CMD installer `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`. `The token '&&' is not a valid statement separator` means you ran that CMD command in PowerShell. `A parameter cannot be found that matches parameter name 'fsSL'` or `'bash' is not recognized` means you ran the macOS/Linux command on Windows. If the command printed the script's text and nothing installed, you ran only half of it: `irm` must be piped to `iex`, and in CMD `curl` needs the `-o install.cmd` part.
7. **The installer downloaded a web page instead of the script.** You'll see `syntax error near unexpected token '<'` in Bash, `< was unexpected at this time` in CMD, `System.Xml.XmlDocument` or HTML-filled parse errors in PowerShell, or a bare `curl: (22) The requested URL returned error: 403`. If the output mentions "App unavailable in region", Claude Code isn't available in your country. Otherwise test the download host with `curl -sI https://downloads.claude.ai/claude-code-releases/latest` (Windows: `curl.exe -sI ...`): a `200` means it's reachable and the failure was probably temporary, so retry; `403` usually means a proxy or filter; no output or `Could not resolve host` means your network blocks it. Behind a corporate proxy, set `HTTPS_PROXY` and `HTTP_PROXY` before installing. On macOS, `brew install --cask claude-code` is an alternative, and on Windows `winget install Anthropic.ClaudeCode`; note that neither updates itself by default.
8. **The install was killed or ran out of permissions.** `Killed` or `Installation was killed before it could finish (exit code 137)` on Linux almost always means the server ran out of memory: installing needs about 512 MB free, and Claude Code needs at least 4 GB of RAM to run. Add a 2 GB swap file (`sudo fallocate -l 2G /swapfile`, `sudo chmod 600 /swapfile`, `sudo mkswap /swapfile`, `sudo swapon /swapfile`) and rerun the installer. `EACCES: permission denied` means a target folder isn't writable: check with `test -w ~/.local/bin && echo writable`, and fix with `sudo mkdir -p ~/.local/bin` and `sudo chown -R $(whoami) ~/.local`. In Docker, set `WORKDIR /tmp` before the install line, because running it from `/` makes it scan the whole filesystem and hang.
9. **TLS errors stopped the download.** `curl: (35) TLS connect error`, `Could not create SSL/TLS secure channel` or `unable to get local issuer certificate` mean the secure connection failed. Update your CA certificates (`sudo apt-get install ca-certificates` on Ubuntu/Debian). In Windows PowerShell 5.1, enable TLS 1.2 with `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` and rerun the installer in that window. Behind a TLS-inspecting proxy, pass its CA with `curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash`, then set `NODE_EXTRA_CA_CERTS` to the same file for Claude Code itself. Our [proxy and SSL certificate errors guide](https://solostackkits.netlify.app/blog/claude-code-proxy-ssl-certificate-error.html) covers the rest of the proxy setup.

## npm, duplicate and platform problems: 3 causes

10. **Two installs are fighting.** An npm global install, a legacy `~/.claude/local/` install from older versions, Homebrew and the native install can all coexist and give you the wrong version or a broken one. List them with `which -a claude` (Windows: `where.exe claude`), plus `ls -la ~/.claude/local/` and `npm -g ls @anthropic-ai/claude-code`. Keep one, ideally the native install, and remove the rest: `npm uninstall -g @anthropic-ai/claude-code`, `rm -rf ~/.claude/local`, `brew uninstall --cask claude-code` or `winget uninstall Anthropic.ClaudeCode`.
11. **The npm install left a placeholder.** `Error: claude native binary not installed` means npm skipped the per-platform optional package or its postinstall script. Remove `--omit=optional` (pnpm `--no-optional`, yarn `--ignore-optional`), check `.npmrc` doesn't set `optional=false`, and reinstall. If you used `--ignore-scripts`, run `node node_modules/@anthropic-ai/claude-code/install.cjs`. In PowerShell, `running scripts is disabled on this system` blocks npm's `.ps1` launchers: run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`, or call `claude.cmd`. `npm error code ENOTEMPTY` during a reinstall means a leftover folder: delete the directory named on the `npm error path` line and any `.claude-code-*` folders next to it, then reinstall. In WSL, `exec: node: not found` means you're using Windows Node from `/mnt/c/`; install Node inside Linux with your package manager or nvm.
12. **The binary doesn't fit your system.** These show up as errors when you run `claude`, not as "not found", but they're often mistaken for a failed install. `cannot execute binary file: Exec format error` in WSL means WSL1: convert with `wsl --set-version <DistroName> 2`. `Error loading shared library libstdc++.so.6` means the musl/glibc variant is wrong; on Alpine run `apk add libgcc libstdc++ ripgrep`. `Illegal instruction` means the wrong architecture or a CPU without AVX (check `uname -m` and `grep -m1 -ow avx /proc/cpuinfo`). `dyld: Symbol not found` or `Abort trap: 6` on a Mac means macOS is older than 13.0. `Claude Code does not support 32-bit Windows` on a 64-bit PC means you opened `Windows PowerShell (x86)`; use the entry without x86.

## Still stuck?

Once `claude --version` works, `claude doctor` gives an automated report for anything else, and `Auto-update failed · Run claude doctor` in the footer is best fixed by running `claude update` in your shell; if updates keep failing or you're stuck on an old version, see [Claude Code not updating](https://solostackkits.netlify.app/blog/claude-code-update-not-working.html). On Windows, if `claude` installs but then fails with Git Bash, PowerShell or WSL errors, see [Claude Code not working on Windows](https://solostackkits.netlify.app/blog/claude-code-windows-not-working.html). If the command runs but sign-in fails, see [Claude Code login not working](https://solostackkits.netlify.app/blog/claude-code-login-not-working.html). If it starts but ignores your config, [settings not applying](https://solostackkits.netlify.app/blog/claude-code-settings-not-applying.html) shows which file each key belongs in, and if your editor can't see it, try [IDE not connecting](https://solostackkits.netlify.app/blog/claude-code-ide-not-connecting.html). Prefer to build a config yourself? Use the [free Claude Code tools](https://solostackkits.netlify.app/tools/) — they run in your browser, no signup.

---

Facts on this page come from Anthropic's Claude Code docs on [troubleshooting installation and login](https://code.claude.com/docs/en/troubleshoot-install) and [setup](https://code.claude.com/docs/en/setup). This guide isn't affiliated with Anthropic.

Once `claude` runs, set it up properly in one go: our [Claude Code Power Config Pack](https://solostackkits.gumroad.com/l/claude-code-config-pack/LAUNCH50?utm_source=hashnode&utm_medium=article&utm_campaign=ssk_hashnode_cnf) has 6 CLAUDE.md templates, permission presets and 8 tested safety hooks, $6 with the launch code while it lasts.

Not ready to buy? Our [free safety hooks](https://solostackkits.gumroad.com/l/claude-code-free-safety-hooks?utm_source=hashnode&utm_medium=article&utm_campaign=ssk_hashnode_cnf) block risky commands before they run.