Claude Code troubleshooting
Fix Claude Code: Command Not Found
Key facts
| Scope | Claude Code |
|---|---|
| Last verified | |
| Decision | Open a new terminal and run `claude --version`. If the command is still missing, confirm the native binary exists in `~/.local/bin` on macOS or Linux, or `%USERPROFILE%\.local\bin` on Windows, then add that directory to your user PATH and reopen the terminal. |
| Official documentation |
Fix Claude Code command-not-found errors by checking installation, executable discovery and shell environment, then verify the command in a fresh terminal.
Open a new terminal and run `claude --version`. If the command is still missing, confirm the native binary exists in `~/.local/bin` on macOS or Linux, or `%USERPROFILE%\.local\bin` on Windows, then add that directory to your user PATH and reopen the terminal.
Match the symptom
- `zsh: command not found: claude` or `bash: claude: command not found`.
- PowerShell says `claude` is not recognized as a cmdlet.
- The installer completed, but an old Claude version or the desktop app opens.
First checks
Collect evidence before changing configuration
which -a claude
ls -la ~/.local/bin/claudewhere.exe claude
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"claude --version
claude doctorDiagnosis 1
Start with a fresh terminal
Installers update PATH for new sessions. The terminal that ran the installer can retain its older environment.
- Close every terminal window, open a new one, and run `claude --version`.
- Confirm you are testing in the same environment where you installed Claude Code: native Windows, WSL, macOS, or Linux.
Decision: If a version prints, PATH is fixed. If not, locate the binary before changing anything else.
Diagnosis 2
Check whether the native binary exists
The native installer uses a predictable user-level location. A VS Code extension alone does not install a terminal command.
ls -la ~/.local/bin/claudeTest-Path "$env:USERPROFILE\.local\bin\claude.exe"Decision: A missing file means the standalone installation did not complete in this environment. Re-run the official installer for the shell you are using.
Diagnosis 3
Add the install directory to PATH
Change the user PATH only after confirming the binary location. Restart the terminal after the change.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcecho 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')Decision: Open a new terminal and run `claude --version`. Do not repeatedly append the directory if it is already present.
Diagnosis 4
Resolve multiple installations
An npm, Homebrew, WinGet, legacy local, or desktop executable can take precedence over the native CLI.
# macOS or Linux
which -a claude
# Windows PowerShell
where.exe claudenpm uninstall -g @anthropic-ai/claude-codeDecision: Keep one intended installation, reopen the terminal, and confirm both the executable location and version.
If it still fails, send this evidence
A useful support request is reproducible and does not expose credentials.
- Output of `claude --version` and `claude doctor`.
- Output of `which -a claude` or `where.exe claude`.
- Operating system, shell, installation method, and whether the repository is native Windows or WSL.
- The exact error text, with tokens and personal paths redacted.
Related paths
Fix the adjacent layer without starting over.
Related account failures
Official sources
Commands and product behavior were checked against first-party documentation on August 13, 2026. Interfaces and authentication flows change; recheck the source when applying this across a team.