What is PATH — and why a program is installed but the terminal can't find it

You installed a program. The installer said "success." You type the command and get command not found.

Here's what happened. The terminal doesn't search your whole disk. It only looks in a short list of folders. Your folder isn't on the list. That list is called PATH.

What is PATH?

PATH is an environment variable holding the list of folders where the terminal looks for commands.

Look at yours:

echo $PATH | tr ':' '\n'

You'll see something like:

/usr/local/bin
/usr/bin
/bin

When you type git, there's no git built into the terminal. It walks the list from top to bottom and looks for a file with that name in each folder. Found it, runs it. Reached the end without finding it: command not found and exit code 127. What that number means is covered in what an exit code is.

How the terminal picks what to run

The main rule: the first match wins. It doesn't look any further.

I put two programs called t in different folders. One prints one, the other two. Then I put the second folder first in PATH:

$ t
two
$ type -a t
t is /tmp/p2/t
t is /tmp/p1/t

type -a shows every candidate. Remember this command: it answers "which program is actually running right now?"

That explains a classic puzzle. You upgraded Node, but node -v shows the old version. Or pip install succeeded, but python can't see the package. There are two versions, and the first on the list isn't the one you think.

One more subtlety. bash remembers where it found a command so it doesn't have to search again. Moved a program and the terminal keeps going to the old address? Clear its memory: hash -r in bash or rehash in zsh.

How to add a folder without breaking the terminal

Say the program lives in ~/.local/bin. Add that folder to the front of the list, keeping the rest:

export PATH="$HOME/.local/bin:$PATH"

The key part is :$PATH at the end. Without it you replace the whole list with one folder. I checked:

$ PATH=~/bin
$ ls
bash: ls: command not found

Don't panic. That setting only lives in the current window. Close it, open a new one, and everything is back.

To make the folder stick, add the export line to your settings file:

• ~/.zshrc on macOS;
• ~/.bashrc on most Linux systems.

Then open a new terminal window. Windows already open won't know about the change. A very common cause of "I added it and it doesn't work" is exactly this.

Why it works in npm run but not directly

You installed a package into your project. npm run build works, but plain vite in the terminal says command not found.

That's correct. Local programs live in node_modules/.bin, and that folder isn't in your PATH. But npm run adds it to the front of the list for the duration of the run. To run one directly:

npx vite

More on how packages are laid out in what npm is.

Why an AI tool can't see what you can see

Here's a newer case. You set up an MCP server in Claude Desktop. npx works in the terminal, but the app says spawn npx ENOENT.

Same cause. The app was launched from the Dock, not from a terminal. It never read your .zshrc. If Node came from nvm or Homebrew, that folder simply isn't in the app's PATH.

The fix is a full path. Get it with which npx and put it in the config:

{
  "mcpServers": {
    "files": {
      "command": "/Users/you/.nvm/versions/node/v22.22.0/bin/npx",
      "args": ["-y", "some-mcp-server"],
      "env": { "PATH": "/Users/you/.nvm/versions/node/v22.22.0/bin:/usr/bin:/bin" }
    }
  }
}

The env block matters. npx itself looks up node through PATH, and without it you get env: node: No such file or directory.

Scheduled jobs break for the same reason: cron has a very short PATH. See why a cron job doesn't run.

Why can't I run a script without ./?

The current folder isn't in PATH, on purpose. Otherwise a stranger's file named ls in a downloaded folder would run instead of the real ls. So you write your own explicitly: ./script.sh.

How does PATH work on Windows?

Same idea, with a semicolon as the separator. To see what runs, use where node. After editing it in "Environment Variables," open a new terminal window.

What if that didn't help?

Find where the program really landed. The installer usually prints it. Common places: ~/.local/bin, ~/.cargo/bin, /opt/homebrew/bin. The basic terminal commands have everything you need to walk the folders by hand.