Introduction
Installed Claude Code but getting this error? Thousands of developers run into this exact issue after installation. You install Claude Code successfully, open your terminal, type claude and instead of launching the AI coding assistant, you get:
zsh: command not found: claude
At first, it looks like the installation completely failed. But in reality, this error is usually very simple to fix. In most cases, your terminal simply cannot locate the Claude Code binary because the install directory is missing from your PATH environment variable.
The good news is that you usually do NOT need to uninstall everything and start over.
This guide walks through every major fix for macOS, Linux, and Windows users, including:
PATH configuration fixes
npm installation problems
Shell config issues
PowerShell fixes
Conflicting installations
Reinstall methods
Advanced diagnostics
By the end of this guide, Claude Code should work normally in every terminal window you open
Quick Fix (Most Users)
If Claude Code was installed correctly but the command is not working, add Claude's install directory to your PATH. This solves the problem for most users in under two minutes.
macOS / Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc claude --version |
Windows PowerShell
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User') [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User') |
Restart your terminal and run claude --version. If you see a version number, the issue is fixed.
Why the "Claude Command Not Found" Error Happens
When you type a command into a terminal, your shell searches through a list of directories stored in something called the PATH environment variable. If the folder containing the Claude executable is not included in PATH, your shell has no idea where to find it.
Important: The error does NOT automatically mean Claude Code is broken. Usually, the binary exists on your computer already. Your terminal simply cannot locate it.
Here are the most common reasons this happens:
1. PATH Does Not Include ~/.local/bin
Claude Code is commonly installed inside ~/.local/bin. If that directory is missing from PATH, the claude command fails.
2. Shell Config Was Not Reloaded
Even after fixing PATH, your terminal session may still use old settings. That is why many developers see Claude working in one terminal but failing in another.
3. Multiple Installations Conflict
Installing Claude via npm, Homebrew, and the native installer simultaneously can create multiple binaries. Your shell may prioritize the wrong one.
4. npm Alias Install Problems
Older npm-based installs sometimes created aliases instead of real PATH entries. The alias works temporarily, then disappears in new terminal windows.
5. Windows PowerShell Issues
Windows users often face PATH registration problems or conflicts with older Claude Desktop installations.
Step 1: Verify Claude Code Is Installed
Before changing PATH settings or reinstalling anything, confirm that the Claude binary actually exists on your system. This saves time and prevents unnecessary reinstalls.
macOS / Linux
ls -la ~/.local/bin/claude
If the file exists, continue to Step 2. If you see No such file or directory, reinstall Claude Code.
Windows PowerShell
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
True = installed. False = reinstall required.
Step 2: Fix the PATH Error
This is the most important step in the entire guide. Your terminal searches specific directories whenever you run a command. If the Claude install directory is missing from PATH, the command cannot work. The solution is to permanently add the install location to your shell configuration file.
macOS (Zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Linux (Bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Now verify:
claude --version
Step 3: Fix npm Alias Install Problems
If you installed Claude Code using npm in older versions, the installer may have created a temporary alias instead of a proper executable entry. This causes a frustrating issue where Claude works in one terminal session but fails in every new terminal window.
Check:
alias | grep claude
If you see something like alias claude='/Users/yourname/.claude/local/claude', add it permanently to your shell config.
Step 4: Remove Conflicting Installations
One of the most overlooked causes of the error is conflicting installations. Many developers accidentally install Claude Code using multiple methods (npm, Homebrew, Native installer, WinGet), creating multiple binaries in different locations.
Run:
which -a claude
If multiple paths appear, remove extra installations:
Remove npm Install
npm uninstall -g @anthropic-ai/claude-code
Remove Homebrew Install
brew uninstall --cask claude-code
Then reinstall using the official installer.
Step 5: Reinstall Claude Code Correctly
If the Claude binary does not exist or your installation appears corrupted, perform a clean reinstall using the official installer. The native installer is the most reliable installation method because it handles PATH setup more consistently than npm.
macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell
irm https://claude.ai/install.ps1 | iex
After installation:
claude --version
Windows-Specific Fixes
Windows users sometimes face additional problems because PowerShell, CMD, Git Bash, and WindowsApps can all affect PATH behavior differently.
Claude Is Not Recognized
This usually means PATH is missing. Add $env:USERPROFILE\.local\bin to your User PATH.
Install Git Bash
Claude Code requires Git for Windows. Install Git with:
"Add Git to PATH" enabled
Restart terminal afterward
Avoid Wrong Installer
Never run the Linux bash installer inside PowerShell. Use:
irm https://claude.ai/install.ps1 | iex
Quick Diagnostic Tool
If Claude Code still does not work after trying the fixes above, use the built-in diagnostic tool. This command automatically checks your installation, PATH configuration, permissions, and environment setup.
claude doctor
This automatically checks:
PATH configuration
Permissions
Install conflicts
Login status
Missing dependencies
Common Mistakes to Avoid
Many developers accidentally create the same PATH problems repeatedly. Avoiding these mistakes can save hours of debugging later.
Using sudo with npm
Avoid: sudo npm install - g @ anthropic - ai / claude-code
Editing the Wrong Shell File
macOS uses ~/.zshrc | Linux usually uses ~/.bashrc
Mixing Install Methods
Do not mix: npm + Homebrew, WinGet + native installer, or multiple versions simultaneously.
FAQ
Run these two commands, then verify with claude --version:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
The Claude binary exists, but its directory is missing from PATH. Follow Step 2 in this guide to fix it permanently.
Add $env:USERPROFILE\.local\bin to your User PATH and restart the terminal.
Prevention Tips
Once Claude Code starts working correctly, take a few extra steps to avoid future PATH problems.
1. Test in a Fresh Terminal
Open a completely new terminal window and run claude --version to confirm the PATH fix is permanent.
2. Use Only One Install Method
Choose one installation method (Native installer, Homebrew on macOS, or WinGet on Windows) and stick with it. Avoid mixing them.
3. Keep PATH Organized
Too many custom PATH entries can create conflicts. Review your shell config occasionally and remove unused entries.
4. Run claude doctor Occasionally
The built-in diagnostic tool helps identify problems before they become serious.
5. Backup Your Shell Config
Keep a backup of ~/.zshrc or ~/.bashrc if you spend time customizing your terminal setup. This makes future recovery easier.
Final Verdict
The "claude code command not found" error is almost always caused by a PATH issue, not a broken installation. In most cases, the fix is simple:
Verify the binary exists
Add ~/.local/bin to PATH
Reload your shell
Remove conflicting installs
Run claude doctor if needed
Once PATH is fixed, Claude Code works normally in every terminal.