You installed Claude Code, excitedly typed claude, and got command not found? The installation isn't broken. Your system just doesn't know where the executable lives. Register the PATH and you're good to go.
The Fix First
One line in your shell config and you're done.
Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Bash (Linux default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Now try claude. It should work.
That's the fix. Everything below is for those wondering "but why does this happen?"
How Is This Different from Windows?
On Windows, installers usually set environment variables for you. You never think about it.
Mac and Linux take a different approach: "your environment, your responsibility." System settings are kept separate from user settings by design. It's a deliberate choice for security and efficiency, but honestly it catches people off guard when they switch from Windows.
What Even Is a Shell?
If you use the terminal, you keep seeing the word "shell." Simply put, it's the translator between you and the operating system.
When you type claude in the terminal, the shell takes that and tells the OS "run this." The black screen itself isn't the shell — it's the software inside that processes your commands.
The two main ones are Zsh and Bash, and each has a different config file. That's why knowing which one you're using matters.
Why 'command not found' Happens
When you type a command, the shell looks through a list of registered directories asking "where's the program with this name?" That list is the PATH environment variable.
Here's the thing: Claude Code installs to ~/.local/bin. But on most systems, this path isn't in PATH by default. The install script tries to add it, but depending on your environment it can get missed or not take effect in your current terminal session.
So we add it ourselves.
How to Check Which Shell You're Using
Type this in your terminal.
echo $SHELL
- If you see
/bin/zsh→ configure~/.zshrc - If you see
/bin/bash→ configure~/.bashrc
Bash may also read ~/.bash_profile or ~/.profile depending on the situation.
Don't worry if the file doesn't exist. The
>>operator creates a new file automatically if there isn't one.
Breaking Down Each Command
Understanding what these commands actually do will help you the next time you install any tool.
echo and >> — Outputs text and appends it to the end of a file. It means "add one line to the bottom of my config file."
export PATH="..." — Prepends ~/.local/bin to your existing PATH. Since it goes at the front, if there are multiple programs with the same name, the one in our specified directory runs first.
source — Shell config files are normally only read when you open a new terminal. source forces a re-read right now. Without it, you'd have to close and reopen your terminal for changes to take effect.
Terminal Command Structure (Bonus)
Terminal commands basically follow a [who] [what] [how] structure.
[executable] [subcommand/verb] [options and arguments]
- Who: the program you're calling (e.g.,
claude,npm,git) - What: the specific action (e.g.,
config,install,commit) - How: additional details or settings (e.g.,
--help,-v, filename)
Once you know this pattern, you can roughly read any command you see for the first time.
Wrapping Up
From now on, whenever you install something and get command not found, no need to panic. Just think "right, it's a PATH thing" and fix it.