Shape the shell
Build PATH deliberately
Add tool directories once, preserve a readable order, and inspect command resolution before blaming an installation.
10 minute lesson
PATH order decides which executable wins when several share a name. On a developer Mac, several always share a name: macOS ships a python3, Homebrew installs one, and a version manager may add a third. The one listed first in PATH is the one that runs.
Most PATH problems come from configuration written in a hurry. Repeatedly prepending directories creates duplicates and hides the reason a command was selected.
Read the PATH like zsh does
Zsh exposes PATH as the path array, which is much easier to read than the colon-separated string:
print -l $path/opt/homebrew/bin
/opt/homebrew/sbin
/usr/local/bin
/usr/bin
/binThen, for any suspicious command, list every candidate in resolution order:
type -a python3
# python3 is /opt/homebrew/bin/python3
# python3 is /usr/bin/python3The first line wins. Everything below it is shadowed — installed, present, and never used by this shell.
Add directories deliberately
Make edits in .zprofile, once, and guard them:
# ~/.zprofile
typeset -U path
[ -d "$HOME/.local/bin" ] && path=("$HOME/.local/bin" $path)typeset -U path tells zsh to keep the array unique, so a re-sourced file cannot stack duplicates. The [ -d ... ] guard means you add a directory only when it exists — a PATH full of dead entries is noise you will debug around later.
Prepend when the new directory must override system tools (version managers rely on this). Append when it only needs to be reachable. Every prepend is a statement: “trust this directory over the OS.” Make that statement on purpose.
When the wrong tool wins
The classic surprise: you install a new Python with Homebrew, but python3 --version still prints the old number. Nothing is broken. /usr/bin/python3 is winning on order, or your shell cached the old location.
After changing PATH, restart the relevant shell and confirm the winner with command -v:
command -v python3
# /opt/homebrew/bin/python3Check resolution first, reinstall never. Almost every “the installation is broken” report on a Mac is really “a different installation answered”.
Lesson completed