This guide is for anyone who installed Claude Code and encountered a command not found error when typing claude in the terminal. This error is not a problem with the installation itself — it's an environment configuration issue where the system hasn't been told where to look for the executable.
Quick Fix
Enter the command that matches your shell environment. This registers the ~/.local/bin directory (where Claude Code installs its executable) into your PATH.
1. Zsh (default on macOS and modern Linux)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
2. Bash (common default on Linux)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
After running the commands, type claude to confirm it works.
1. Why Mac/Linux Handles This Differently Than Windows
On Windows, installers often automatically register executables into the system PATH, so users rarely need to manage it manually. On Mac and Linux (Unix-based systems), the philosophy is different: users are expected to explicitly control their environment configuration.
This design keeps system-wide settings from interfering with individual user preferences, improving security and predictability. It's often the first surprising difference for developers coming from Windows.
2. What Is a Shell?
If you've spent any time in the terminal, you've probably heard the word "shell." A shell is simply a command interpreter — the bridge between you and the operating system.
- What it does: When you type
claudein the terminal, the shell reads that text, translates it into a signal the OS can understand, and asks the OS to run it. - What it isn't: The black window (terminal emulator) itself is not the shell. The shell is the software environment running inside it that processes your commands.
- Common types: Zsh and Bash are the most common. Each shell reads its configuration from a different file, which is why identifying your shell matters.
3. Root Cause: What PATH Actually Does
When you type a command in the terminal, the shell searches through a list of directories to find a matching executable. That list is the PATH environment variable.
- The missing path: Claude Code's native installer places the executable in
~/.local/bin. However, most systems don't include this directory in the default PATH. - Why it's per-user: Unix systems keep each user's environment configuration in their own dotfiles. The installer may attempt to update these files, but it can fail silently or not apply to an already-open terminal session.
4. Finding the Right Config File for Your Shell
Run echo $SHELL in your terminal to see which shell you're using.
- Zsh (default on modern macOS): Uses
~/.zshrc - Bash (standard on Linux, older macOS): Usually
~/.bashrc, but may use~/.bash_profileor~/.profiledepending on login type
Tip: What if the file doesn't exist? These files may not be present on a fresh system. The
>>operator in the commands above will automatically create the file if it doesn't exist, so you can proceed without worry.
5. Breaking Down the Fix Commands
Understanding what each part does helps you solve similar problems in the future.
1. echo and >> (writing to a file)
echo outputs text, and >> appends that text to the end of a file. Together, they add one line to your shell config: the instruction to include ~/.local/bin in your PATH.
2. export PATH="..." (setting search priority)
This prepends $HOME/.local/bin to the existing path list ($PATH). Placing it at the front means if multiple programs share the same name, the one in your local bin directory will be found first.
3. source (applying changes immediately)
Shell config files are normally read once when the terminal opens. The source command forces the already-running terminal to re-read the file and apply changes immediately — no restart needed.
6. How Terminal Commands Are Structured
Terminal commands follow a predictable pattern:
[program] [subcommand] [options and arguments]
- Program: The name of the tool to run (e.g.,
claude,npm,git) - Subcommand: The specific action to take (e.g.,
config,install,commit) - Options/Arguments: Additional details that modify the behavior (e.g.,
--help,-v, a filename)
Once you internalize this structure, unfamiliar commands become much easier to read and reason about.
Wrapping Up
The next time you see command not found after installing any tool, don't panic. Just think: "The PATH probably needs updating." You now have both the fix and the understanding to handle it confidently.