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 whysource ~/.bashrcerrors 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:
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:
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:
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:
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.