Skip to content

Troubleshooting

claude: command not found / claude not recognized

If the installer said "installation complete", the binary was installed — what's failing is the PATH (your terminal just can't find it yet). Don't reinstall — it's a path problem, not an install problem.

Where the binary lives (exact — don't guess)

The native installer puts claude at ~/.local/bin/claude (a symlink → ~/.local/share/claude/versions/<version>). It is NOT in ~/.claude/bin or /usr/local/bin. ~/.claude/ is configuration, not the binary. On Windows: %USERPROFILE%\.local\bin\claude.exe.

Correct diagnosis (in order):

# 1) Does the binary exist? — this is the AUTHORITATIVE check
ls -l ~/.local/bin/claude
# 2) Does it run via absolute path? If it prints a version → installed, it's just PATH:
~/.local/bin/claude --version
# 3) Fix the PATH in the file YOUR shell reads (see the note below) and reload.
#    Example for zsh (modern macOS):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Open a new terminal (the PATH doesn't update in the current session). If it's still not recognized, check that %USERPROFILE%\.local\bin is on the user PATH.

Don't conclude 'it didn't install' if which claude returns nothing

An empty which claude, or a find ~/.claude ... that finds nothing, does NOT mean the install failed — it almost always means you looked in the wrong place. The binary is at ~/.local/bin/claude. Always check with ls -l ~/.local/bin/claude (or run ~/.local/bin/claude --version); never infer "not installed" from a which/find in other paths.

The PATH file depends on YOUR shell — not everyone uses ~/.bashrc

Find your shell with echo $SHELL and use the right file:

  • macOS with zsh (modern default; prompt ends in %) → ~/.zshrc.
  • macOS with bash (prompt ends in $) → ~/.bash_profile. A bash login shell on macOS does not read ~/.bashrc → that's why source ~/.bashrc errors or "does nothing".
  • Linux → usually ~/.bashrc.

Why it happens

A script cannot change the PATH of the terminal that invoked it. You always need a new terminal or source after installing.

claude --version prints nothing / stays the same

Almost always it's PATH: you're invoking a claude that doesn't exist in this session. Try with the absolute path:

~/.local/bin/claude --version

If it does print with the absolute path, it's PATH (see above).

macOS: requires macOS 13.0 (Ventura) or later

Claude Code doesn't support earlier versions of macOS. Check with sw_vers; if ProductVersion is below 13.0, update macOS or use a newer Mac.

npm: EACCES: permission denied

The global npm directory isn't writable. Don't use sudo (it causes permission and security problems). Configure a user prefix:

mkdir ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc

Better yet: use the native installer, which doesn't depend on npm.

curl: (403) or syntax error near unexpected token '<'

Usually a proxy/firewall returning HTML instead of the script. Check your network/proxy and retry; if it persists, try another method (npm, Homebrew) or check the official installation troubleshooting guide.

Windows: the PowerShell script won't run (execution policy)

Run in the same console, without admin:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force

and launch the command again. Make sure you're in PowerShell (not CMD).

Can't sign in / "not included in your plan"

Claude Code does not work with the free Claude.ai plan. You need Pro, Max, Team or Enterprise, or a Console account with API. Within a session, re-authenticate with /login.

I installed on a server / over SSH and the browser won't open

On a VPS or SSH session with no GUI, the login can't open a browser. Claude Code shows you a URL and a code: copy them, open them in the browser on your local machine, authorize, and come back. If it hangs on Signing in…, force the terminal flow:

unset DISPLAY && claude

Network error / "region not supported"

Claude Code isn't available in every country. Check the list of Anthropic-supported countries. If your region is supported, it's usually a proxy/firewall: try another network or the official install guide.

The Claude folder grew a lot (hundreds of MB)

The auto-update keeps old versions in ~/.local/share/claude/versions/. Free them up by leaving only the active one:

# dry-run (shows what it would delete):
./scripts/claude_cleanup.sh
# actually delete:
./scripts/claude_cleanup.sh --apply

claude still appears after uninstalling

There's a conflicting installation (several copies or an alias). Find them:

which -a claude

and remove the leftover copy or the alias in your shell profile.


Your case isn't here? Open an issue on GitHub or check the official documentation.