Fix "zsh: command not found: claude" — Claude Code CLI

Typed claude and got zsh: command not found: claude? Your shell searched every directory in PATH and found no executable by that name. The install is usually fine — the shell simply cannot see it.

The Error

$ claude
zsh: command not found: claude

Or, depending on your shell:

bash: claude: command not found
'claude' is not recognized as an internal or external command,
operable program or batch file.

All three mean the same thing. Note the distinction from a different error you may also have seen: zsh: permission denied: claude means the shell found the file but could not execute it, which is covered separately in Claude Code permission errors.

Why This Happens

1. You are still in the shell you installed from. A shell keeps the PATH it started with for its entire lifetime and cannot see a directory added part-way through. This is the single most common cause.
2. ~/.local/bin is not on your PATH. The native installer puts the binary there, but many shell configurations do not include it by default.
3. The PATH line is in the wrong file. Adding it to ~/.bashrc does nothing if your shell is zsh, which is the default on modern macOS.
4. Only the VS Code extension is installed. It bundles a private copy of the CLI and does not place claude on your PATH.
5. Nothing is installed. The install failed part-way and the error was missed in the scrollback.

Fix 1: Open a New Terminal

Before anything else, close the terminal and open a fresh one, then:

claude --version

A working installation prints a version number such as 2.1.211 (Claude Code). If that works, you are done — the old session simply had a stale environment.

Fix 2: Check Whether the Binary Exists

Establish which problem you actually have:

ls -la ~/.local/bin/claude

• A symlink into ~/.local/share/claude/versions/ → the native install is present. This is a PATH problem; go to Fix 3.
• No such file or directory → nothing is installed there; go to Fix 4.

On Windows, check Test-Path "$env:USERPROFILE\.local\bin\claude.exe" in PowerShell.

Fix 3: Add the Install Directory to PATH

First confirm which shell you are actually running — this is where most attempts go wrong:

echo $SHELL

Then edit the matching startup file:

# Zsh (default on modern macOS) - note the file is ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash (default on most Linux distributions)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell - adds to your User PATH permanently
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Confirm the directory is now present:

echo $PATH | tr ':' '\n' | grep -F "$HOME/.local/bin"

If that prints /Users/you/.local/bin or /home/you/.local/bin, the directory is on your PATH. For fish, Nushell or another shell, use that shell's own PATH syntax and restart the terminal.

Fix 4: Install the CLI

If the binary is genuinely absent, install it. The native installer needs no Node.js:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Homebrew, WinGet, npm and the Linux package repositories are all covered in our full guide to installing the Claude Code CLI.

Watch the installer's output rather than assuming it succeeded. If it reported an EACCES or other permission failure, that is a different problem — see Claude Code installation errors.

Fix 5: Check for Conflicting Installations

Multiple copies cause the confusing variant where claude resolves but behaves oddly, or where an update appears to do nothing:

which -a claude                          # every claude on your PATH
ls -la ~/.local/bin/claude               # native install
ls -la ~/.claude/local/                  # legacy local npm install
npm -g ls @anthropic-ai/claude-code      # npm global install

where.exe claude

No such file or directory from those ls commands is not an error — it just means nothing is installed there. If you find more than one, keep the native install at ~/.local/bin/claude and remove the rest:

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local
brew uninstall --cask claude-code

The WSL Trap

If you work on Windows with WSL, this error has a specific and easily missed cause: a Windows install does not give you a claude command inside WSL, and a WSL install does not give you one in PowerShell. They are separate environments with separate filesystems and separate PATHs.

Running the Windows PowerShell installer places claude.exe under your Windows profile. Your WSL distribution cannot see that as claude — it is a different operating system with its own ~/.local/bin. The fix is to run the Linux installer inside the WSL terminal:

# Run this from inside WSL, not from PowerShell
curl -fsSL https://claude.ai/install.sh | bash

Then launch claude from the WSL terminal too. The same applies in reverse: installing inside WSL leaves PowerShell without the command. If you use both, install in both — it is not a duplicate installation problem, because they cannot collide.

Verify the Fix

Open a brand-new terminal — not the one you just edited config in — and run:

claude --version
claude doctor

claude doctor prints read-only installation and settings diagnostics without starting a session, including install health and any warnings with suggested fixes. It is the fastest way to confirm the shell and the CLI now agree.

If claude works in your terminal but your editor still reports it missing, that is a separate environment problem — see Could not locate the Claude CLI on PATH.

Prevention

• After any install that touches PATH, open a new terminal rather than trusting the current one.
• Keep to one installation method. Mixing the native installer, Homebrew and npm is how duplicate-install confusion begins.
• If you use several shells, put the PATH export in the file each one reads, or in a shared file both source.
• On a new machine, run claude doctor once after installing — it surfaces PATH and launcher problems before they interrupt real work.

Summary

1. Open a new terminal first — the install session has a stale PATH
2. ls -la ~/.local/bin/claude tells you whether this is a PATH problem or a missing install
3. Add ~/.local/bin to PATH in the file your actual shell reads (echo $SHELL to check)
4. Install the CLI if the binary is genuinely absent; the VS Code extension does not provide it
5. Run which -a claude to catch duplicate installations
6. Confirm with claude --version and claude doctor in a fresh terminal