zsh: command not found: claude - How to Fix It on macOS

The "zsh: command not found: claude" error means your shell cannot find the Claude Code binary because its install directory is not on your PATH. The native installer places the binary at ~/.local/bin/claude, and on a fresh macOS setup that directory is usually not in zsh's search path, so the fix is one line in ~/.zshrc followed by a shell reload. This guide gives the exact fix for every install method (native installer, npm, Homebrew) plus the verification steps from Anthropic's official troubleshooting docs.

Why the Error Happens

Zsh prints "command not found: claude" when none of the directories in your $PATH variable contain an executable named claude. The install almost always succeeded; the shell just does not know where to look. On macOS this happens for three common reasons:

• The install directory is not on PATH. The native installer writes to ~/.local/bin/claude, and macOS does not include ~/.local/bin in the default zsh PATH.
• You have not restarted the shell. PATH changes in ~/.zshrc only apply to new shell sessions or after source ~/.zshrc. The terminal window you installed from still has the old PATH.
• You only installed the VS Code extension. Anthropic's docs are explicit that the VS Code extension bundles a private copy of the CLI inside the extension directory and does not add claude to PATH. If ~/.local/bin/claude does not exist, run the standalone install first.

If you have not installed Claude Code at all yet, start with our how to install Claude Code walkthrough and come back here only if the command still is not found.

The Quick Fix for zsh on macOS

For the standard native install, adding ~/.local/bin to your PATH in ~/.zshrc fixes the error permanently. First confirm the directory is missing from PATH:

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

If that prints a path like /Users/you/.local/bin, PATH is fine and your problem is elsewhere (jump to conflicting installations). If it prints nothing, add the directory and reload:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --version

Two details matter here. Use $HOME rather than ~, because a tilde inside double quotes never expands, which produces a broken PATH entry that fails silently. And if you prefer not to source, fully close and reopen your terminal instead; a new tab in some terminal apps reuses the old environment.

Fixes by Install Method

Each Claude Code install method puts the binary in a different place, so the right PATH entry depends on how you installed:

npm installs: find where npm puts global binaries with npm config get prefix; the executables live in that prefix's bin folder. If it prints something like /Users/you/.npm-global, add this to ~/.zshrc:

export PATH="$(npm config get prefix)/bin:$PATH"

Resist the classic Stack Overflow reflex of rerunning the install with sudo npm install -g. It "fixes" permissions by creating root-owned files in your npm tree, which breaks future updates. If you hit npm permission errors, Anthropic's recommended path is switching to the native installer instead.

Node version managers: if you installed via npm under nvm, each Node version has its own global bin. Switching Node versions with nvm use silently drops claude off your PATH; reinstall under the new version or, better, migrate to the native installer so the binary survives Node switches.

Check for Conflicting Installations

Multiple Claude Code installs can shadow each other and produce version mismatches or a broken launcher. List every claude binary zsh can see:

which -a claude

Then check the three places a binary can come from, per the official docs: ~/.local/bin/claude is the native install, ~/.claude/local/ is a legacy local npm install created by older Claude Code versions, and npm -g ls @anthropic-ai/claude-code reveals a global npm install. Anthropic recommends keeping only the native install and removing the rest:

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local
brew uninstall --cask claude-code   # only if you also brew-installed it

Your settings, sessions, and login survive this cleanup; they live in ~/.claude/ (minus the local folder), not in the binary. If login breaks afterward, our Claude Code login fix guide covers re-authentication.

Verify the Fix

Three commands confirm the error is gone for good. Run them in a brand new terminal window, not the one you patched with source, so you prove the fix persists across sessions:

command -v claude        # should print /Users/you/.local/bin/claude
claude --version         # should print a version number
claude doctor            # full diagnostic report

claude doctor is the built-in diagnostic that checks the install, auto-updates, and permissions in one pass. If claude --version works but the app misbehaves at runtime, that is a different class of problem; start with our Claude Code guide or check whether Claude is down before debugging locally.

When It Is Not a PATH Problem

A small share of "command not found" reports are not PATH issues at all, and PATH edits will not fix them. Three cases worth ruling out:

• The binary crashed and deleted itself mid-update. Early Claude Code versions had a known failure mode where a crash during update left a dangling command, tracked in GitHub issue #471. Reinstalling with the native installer resolves it.
• macOS is too old. Claude Code requires macOS 13.0 or later; on older systems the binary fails with dyld errors that can be mistaken for install problems. Check About This Mac before spending time on PATH.
• The install itself failed. If ls ~/.local/bin/claude prints "No such file or directory" and npm shows nothing, there is nothing to find. Rerun the installer and watch for network or permission errors; the official troubleshooting page maps each installer error message to a fix.

These are the honest edge cases; for roughly nine out of ten people hitting this error on macOS, the one-line ~/.zshrc fix in the quick-fix section is the complete answer.

Related Guides

• How to Install Claude Code: Step-by-Step Guide
• Claude Code Guide: Everything You Need to Know
• Claude Code Login Not Working: How to Fix It
• Claude Code OAuth Error 500: How to Fix It