Fixing a Claude Code install that didn't work
The three install problems that cover almost everyone (a permissions error, command not found, two installs at once) and the one-minute fix for each.
Goes with Claude Code — Getting Started, after lesson 1: Install Claude Code.
Show transcript
Hi, I'm Opal. In lesson one, you installed Claude Code. If that went smoothly, skip this one. If it didn't, stay with me.
Three problems cover almost everyone, and each one takes a minute to fix. The first is a permissions error. You ran the npm install, and it stopped with EACCES, permission denied. The tempting fix is to put sudo in front and run it again.
Please don't. Anthropic's own docs warn against it, because it can lead to permission problems and security risks. Instead, switch to the native installer. It's one line, curl dash f s S L, the claude dot ai install script, piped to bash.
It doesn't use npm at all, it installs into a folder in your home directory, and it keeps Claude Code up to date on its own. The exact line is on this lesson's page. The second problem is the most common one. The install finishes, you type claude, and your terminal says command not found.
Nothing is broken. Your terminal just doesn't know where to look yet. The native installer puts claude in a folder called dot local slash bin, inside your home folder, and on a lot of Macs that folder isn't on your path. The installer even tells you so, under setup notes.
The fix is two commands. The first adds that folder to your path in your z s h r c file, so every new terminal can find it. The second, source, applies it to the window you're in. Then type claude dash dash version, and you'll get a number back.
If you use the terminal inside your code editor, quit the editor and reopen it, because it keeps the path it started with. The third problem is two installs at once. Say you had the native install, then later ran the npm install too. Now claude dash dash version shows an old number, or updates seem to do nothing.
Type which dash a claude. It lists every claude your terminal can find, in the order it tries them. If you see more than one, keep the native one in dot local slash bin, and remove the npm copy with npm uninstall dash g. Then type hash dash r, or open a fresh terminal.
One thing that isn't a problem. If npm warns you about your Node version, the install still finishes and claude still runs. The program it installs doesn't use Node at all. And when you're not sure what's wrong, type claude doctor.
It checks your install and tells you what it finds, without changing anything. So here's the one thing to take away. Don't reach for sudo. Use the native installer, put its folder on your path, and keep one copy.
When claude dash dash version answers with a number, you're ready for lesson two.
If your install went smoothly, skip this one. If it didn't, three problems cover almost everyone.
1. A permissions error (EACCES)
The npm install stopped with EACCES, permission denied. Don't put sudo in front and run it again: Anthropic's docs warn against it. Use the native installer instead. It doesn't use npm, installs into a folder in your home directory, and keeps Claude Code up to date on its own.
curl -fsSL https://claude.ai/install.sh | bash
2. command not found
The install finished, but typing claude gets command not found. Nothing is broken: the native installer puts claude in ~/.local/bin, and on a lot of Macs that folder isn't on your path yet. Add it, apply it to this window, and check:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --version
If you use the terminal inside your code editor, quit the editor and reopen it, because it keeps the path it started with.
3. Two installs at once
claude --version shows an old number, or updates seem to do nothing. List every claude your terminal can find, in the order it tries them:
which -a claude
If there's more than one, keep the native one in ~/.local/bin and remove the npm copy, then clear the terminal's memory of the old one (or open a fresh terminal):
npm uninstall -g @anthropic-ai/claude-code
hash -r
Not a problem: a Node version warning
If npm warns about your Node version, the install still finishes and claude still runs.
When you're not sure
claude doctor
It checks your install and tells you what it finds, without changing anything. When claude --version answers with a number, you're ready for lesson two.
Try these prompts
- My terminal says `claude: command not found` right after I installed Claude Code on a Mac with zsh. Walk me through checking whether ~/.local/bin is on my PATH, one command at a time.Open in ChatGPT (new tab)Open in Claude (new tab)
- Here's what `which -a claude` printed: [paste it]. Which copy should I keep, and what's the command to remove the other one?Open in ChatGPT (new tab)Open in Claude (new tab)
- Here's what `claude doctor` printed: [paste it]. Explain each line in plain words and tell me which problem to fix first.Open in ChatGPT (new tab)Open in Claude (new tab)