Your shell finds a tool by searching folders in order

How does your terminal find a tool? You type a name and a program runs. The shell finds it by looking through a list of folders, in order, and the first file with that name wins. The list is built as the shell starts, and where each tool sits in it is its installer's choice.

  1. 01The question
  2. 02Typing a name
  3. 03Where PATH comes from
  4. 04The folders
  5. 05Two ways to move in

01The question

Is Bun installed in /bin, with the system's own commands? No. It lives in a hidden folder in your home, ~/.bun/bin/bun, and the terminal finds it anyway. Node is somewhere else again, /usr/local/bin, and Homebrew's tools somewhere else still. So how does typing a name find the right file, wherever it is?

The answer is one variable, PATH: a list of folders the shell searches in order. The rest follows from it: where that list comes from, what the folders on it are for, and why each installer puts its tool where it does.

02Typing a name

The window you type into is the Terminal app. What reads your typing is a , an ordinary program; on a Mac it is zsh, the file /bin/zsh. When you type bun install, the shell splits off the first word and has to find a file called bun.

It doesn't search the whole disk. It reads , an holding a list of folders separated by colons, and looks in each folder in turn. The first file with that name runs. If none has it, you get command not found. The name is literal: it is a list of paths. The capitals are a Unix habit for environment variables, like HOME and USER, to tell them apart from a script's own variables.

Fig 01

Looking…

Type a command and watch the shell look down PATH. Ink is where it was found; dots are folders checked and passed.

First match wins. That matters more than it sounds. On a Mac with two copies of Node, say Node 20 in /usr/local/bin from the nodejs.org installer and Node 22 in ~/.local/bin, brought along by an agent tool, whichever folder comes earlier in the list wins. If ~/.local/bin is first, typing node runs 22 and the other is never reached. which -a node lists every match in order.

A command is a file. PATH is the order the shell looks in, and the first file it finds is the one that runs.

Apps you click on aren't found this way. Finder and Launchpad open Chrome or Figma from /Applications, and PATH plays no part. PATH is only for names typed into a shell. An app can join in by putting a file on PATH, which is how code . opens VS Code.

03Where PATH comes from

PATH isn't kept in one file. Every running program holds its own copy of its environment, inherited from whatever started it, and each shell builds its PATH as it starts, in steps.

  • The system's list comes first. /etc/zprofile runs Apple's path_helper, which reads /etc/paths (/usr/local/bin, /usr/bin, /bin, /usr/sbin, /sbin) and adds whatever installers dropped into /etc/paths.d, such as Homebrew's.
  • Then your own files: ~/.zprofile, then ~/.zshrc. The dot hides the file in Finder; rc stands for run commands. It is a script zsh runs every time a new shell starts.
  • An installer that wants to be found adds a line like export PATH="$HOME/.bun/bin:$PATH": the new folder, then everything already there. That puts it at the front.

So the last line written is the first folder searched, and that is why a tool added this way beats /usr/local/bin. Bun's installer writes its two lines itself, and says so when it finishes.

Two things trip people up. A shell that's already open read .zshrc when it started, so it won't see an edit until you open a new one or run source ~/.zshrc, which runs the file again in this shell. And each shell reads only its own file: zsh never reads .bashrc, so a line added there does nothing. echo $SHELL says which one you have; Macs have started with zsh since Catalina in 2019. zsh is the program and .zshrc its settings, the same as Bash and .bashrc.

The list is built fresh by every shell as it starts, from the system's folders and then yours, and the last one added is searched first.

04The folders

The folders that hold programs differ in two ways: who put the files there, and who is allowed to change them. /usr/bin holds what came with the system, like curl; /usr/local/bin and Homebrew's folder hold what was added to this machine afterwards; a folder in your home holds what is yours alone.

Fig 02
Folder
/usr/local/bin
Put there by
Installers you ran
Changed by
Anyone with sudo
Used by
Every user
On PATH
Yes
For example
node, code
Pick a folder: whose files are these, who may change them, and does the shell look there?

On a Mac since Big Sur, /bin, /usr/bin and the rest of Apple's system live on a sealed volume that is mounted read only. Not even can write there, and an update replaces it whole. /usr/local and /opt/homebrew sit outside the seal: they belong to the machine, every user can run what is in them, and writing to them takes sudo or, for Homebrew, an owner set once at install. Your home, ~, is /Users/<you>: only yours, and it needs no permission from anyone. On a shared server that difference matters; on a laptop with one person it mostly decides whether you're asked for a password.

The split between /bin and /usr/bin was a disk running out, not a ranking of importance. Many Linux systems have since merged them, and /bin is just a link to /usr/bin. On a Mac both are Apple's, and /bin holds the shells themselves.

05Two ways to move in

Why is Node in /usr/local/bin and Bun in ~/.bun/bin, rather than ~/bin/.bun? The tool doesn't decide that. The installer does. There are two habits, and Homebrew sits between them.

Into the shared folder. The installer from nodejs.org drops the node file straight into /usr/local/bin, alongside everyone else's, and npm into /usr/local/lib. Every user on the machine gets them. It asks for your password, because those folders aren't yours, and taking it out again means knowing every place it wrote to.

Into a folder of its own. Bun makes ~/.bun, puts its file in a bin folder inside it and adds that folder to PATH. Claude Code does the same in ~/.local: ~/.local/bin/claude is a link to one file in ~/.local/share/claude/versions/, and earlier versions wait beside it. No password, nothing touched outside your home, and deleting one folder removes it. That's why the folder comes first and bin sits inside it: the folder is the tool's own, bin is the one part of it PATH needs to see.

Homebrew does both. It keeps the real files in a cellar, a folder per tool per version, then puts a for each in one shared bin: /opt/homebrew/bin/pnpm points to ../Cellar/pnpm/10.30.2/bin/pnpm. Upgrading means a new folder and moving the link. On Apple's own chips Homebrew lives in /opt/homebrew; on Intel Macs it was /usr/local.

Fig 03
Asks for a password
Yes. These folders aren't yours
Gets on PATH
Nothing to add. /usr/local/bin is on it already
To take it out
Five places, by hand, with sudo
Four installers. Ink is what each one put on the disk; a dashed box is a link, with a line round to the file it points at. Then take each one out again.

Node can arrive either way. Version managers such as nvm put each Node in its own folder in your home, the way Bun does. Once the folder is on PATH, the shell can't tell the difference.

Where a tool lives is the installer's choice. To the shell it only matters that the folder is on PATH.

Connected

Side threads

Questions that came up once the main idea began to hold, kept as they were asked. Each opens beside the paragraph it grew from.

Terms

Checked

What the chat had wrong or only half right, against sources. The note above already says the corrected thing.

  1. /usr stands for "Unix System Resources", not user.It held the users' home folders. System files spilled onto that second disk when the first filled, in early Unix. The longer name came later.Rob Landley, BusyBox list, 2010
  2. PATH starts in ~/.zshrc.It starts before that: /etc/zprofile runs path_helper, which reads /etc/paths and /etc/paths.d. The .zshrc only adds folders in front.macOS, /etc/zprofile and man path_helper
  3. /usr/bin needs sudo to change, and the shell is in /bin because the system needs it to boot.On a modern Mac neither folder can be changed, even with sudo: both are on Apple's sealed, read-only system volume. The /bin and /usr/bin split was about disk space, and the Mac boots without a shell.Apple Platform Security, Signed system volume
  4. The kernel launches the shell.The kernel starts launchd, which starts everything else. Terminal asks for a login shell when it opens a window.Apple, The boot process
  5. Node puts itself in /usr/local/bin; that is Node's old-school convention.It is the nodejs.org installer's choice. Homebrew puts Node in /opt/homebrew, and nvm puts each version in its own folder in your home.nvm, README
  6. Bun has Node.js built in, so you don't need Node.Bun has no Node inside. It is a runtime of its own that runs most Node code.Bun docs, Node.js compatibility
  7. Claude Code is a fully native binary, not a JavaScript app.It is JavaScript compiled by Bun into one file with Bun's runtime inside. It needs no Node because it carries its own runtime.Bun blog, Bun joins Anthropic