Homebrew Field Guide

01Live Lookup Toolinteractive

Type any Homebrew formula or cask. This pulls real, live data from Homebrew's public API — description, dependencies, popularity, and the actual command(s) it provides — then generates the exact investigation commands to run on your own Mac. Click any dependency chip to dig into it.

Try:

Why it can't actually run brew for you: a web page is sandboxed away from your shell for security — no website can execute commands on your Mac. So the live data (what's public) is fetched and shown here, and the machine-specific answers (brew uses --installed, which) are generated as copy-paste commands. One click copies them; paste into iTerm.

02What Homebrew Is

Think of Homebrew as an app store for the terminal. You type brew install <name> and it fetches the software, all the other software that software needs, and keeps a tidy record so you can update or remove it later. Two vocab words unlock everything else:

Formulabrew install

A command-line program or library — things you run or that other tools rely on. eza, git, node, jq are all formulae. This is the default; brew install eza installs a formula.

Caskbrew install --cask

A graphical Mac app (a .app you click) or a font — things with a window, not a terminal command. iterm2, google-chrome, a Nerd Font. Installed with the --cask flag.

The big idea you'll keep meeting: when you install one thing, Homebrew quietly installs everything it depends on. It's normal for a machine to have several times more packages installed than you ever explicitly asked for — the rest are dependencies pulled in automatically. That gap is the whole reason the categories below exist.

Where it lives: on Apple Silicon, Homebrew installs everything under /opt/homebrew and symlinks the commands into /opt/homebrew/bin (which is on your PATH). It never touches macOS system files — that's why it's safe and easy to undo.

03The 5 Categoriesmental model

Everything Homebrew installs falls into one of five buckets. The confusing part — "what do I actually run vs. what just sits there?" — disappears once you can place a package in the right bucket. Each card lists common examples.

1 · Things you type and run

Foreground tools

You type the name, it does a job, it finishes and hands your prompt back. This is "running it directly." The bulk of what you install lives here.

ezabtophtoptreeghtmuxtldryt-dlpjqcowsay

2 · Things that load when a terminal opens

Shell plugins

You never type these by name. Your ~/.zshrc "sources" them every time a terminal opens, and they quietly change how the shell behaves — your prompt, your autosuggestions, the green/red coloring as you type.

powerlevel10kzsh-autosuggestionszsh-syntax-highlighting

3 · Things that run in the background, forever

Services & daemons

These start up and keep running whether or not a terminal is open — they listen for work. Managed by brew services, not typed by you. Check what's running with brew services list.

postgresqlredisnginxollama

4 · Things other programs run — never you

Libraries, runtimes & build tools

You installed these (or they got pulled in), but you rarely or never type them — they exist so other software can run. Runtimes like node power every JS tool; git-delta runs inside git; and the ~109 invisible dependencies are spare parts other tools are built from.

nodegogit-deltalibpqpkgconfonigurumaopenssl

5 · GUI apps & fonts

Casks — you click, not type

Installed by brew but you click them, you don't type them. Fonts are installed but never "run" — just rendered. (A few casks, like 1password-cli, do add a command — op.)

google-chromevisual-studio-coderectangleiterm2font-meslo-lg-nerd-font

The 2-second test: run which somename. If it prints a path → you can type it (bucket 1 or 4). If it prints nothing → it's a library, plugin, service, or GUI app you don't invoke by name. Then run brew uses --installed somename: if other packages are listed, something needs it — leave it alone.

04Investigation Commands

The toolkit for answering "what the heck is this thing, and can I remove it?" Every command below is safe — they only read information, they never change anything.

What is it?brew desc

One-line description. Use brew info for the full picture: version, dependencies, caveats, install size, and whether it's currently installed.

brew desc eza        # one-liner
brew info eza        # full details + caveats

Is it safe to remove?brew uses

Lists what installed packages depend on this one. Empty output = nothing needs it, so it's safe to uninstall. Output = something relies on it; leave it.

brew uses --installed oniguruma
# → git-delta   (so don't remove it)

What does it drag in?brew deps

The reverse of brew uses — what this package needs to function. The --tree view shows the whole dependency chain nested.

brew deps git-delta          # flat list
brew deps --tree git-delta   # nested tree

Can I type it? Where is it?which

Prints the path to a command, or nothing if it isn't one. The command name often differs from the formula name (formula git-delta → command delta). type also reveals aliases.

which delta     # /opt/homebrew/bin/delta
type ls         # reveals your eza alias

How do I use it?tldr / man

tldr gives the handful of real-world examples you actually want; man is the full manual (press q to quit). brew home opens the project's website.

tldr tar          # the 5 commands you'll use
man rsync         # full manual (q to quit)
brew home eza     # open homepage

What did I choose vs. what's a dependency?brew leaves

brew leaves --installed-on-request shows only the packages you asked for — not the dependencies. The fastest way to see your real footprint vs. everything that came along for the ride.

brew leaves --installed-on-request  # your picks
brew list --formula | wc -l         # total count

05Install & Remove

The everyday verbs. Installing is always safe; removing is too, as long as you check brew uses --installed first (or just let brew autoremove handle the orphans for you).

Install a tool or appinstall

Default installs a formula (CLI tool). Add --cask for a GUI app or font. Search first if you're not sure of the exact name.

brew install wget          # a CLI tool
brew install --cask vlc    # a GUI app
brew search pdf            # find the right name

Remove a packageuninstall

Removes the package — but not the dependencies it brought along. Those become "orphans," cleaned up separately (next card).

brew uninstall wget
brew uninstall --cask vlc

Sweep up orphaned dependenciesautoremove

Removes dependencies that nothing needs anymore — the leftovers after uninstalling something. Safe: it only touches packages no installed leaf depends on.

brew autoremove        # shows what it'll remove first

Reclaim disk spacecleanup

Deletes old downloaded versions and stale cache. Add -n (dry run) to preview without deleting anything.

brew cleanup -n    # preview what'd be freed
brew cleanup       # actually do it

06Maintenance

Run these every week or two to keep things current and healthy. None of them remove software you chose.

Refresh the catalogupdate

Updates Homebrew itself and its list of available packages. It does not upgrade your installed software — it just learns what's new.

brew update

Upgrade your softwareupgrade

Installs newer versions of what you have. Check first with brew outdated, or upgrade just one thing by naming it.

brew outdated      # what has updates?
brew upgrade       # upgrade everything
brew upgrade eza   # just one

Health checkdoctor

Diagnoses common problems and tells you how to fix them. "Your system is ready to brew" means all good. Run it when something acts up.

brew doctor

Manage background servicesservices

See and control the daemons from category 3 — what's running, what errored, and start/stop/restart them.

brew services list             # status of all
brew services restart tailscale

07Safe Cleanup

Want to thin out things you don't recognize without breaking anything? Follow this exact order. The golden rule: only remove a "leaf" that nothing else uses.

The safe cleanup workflow

# 1. See only the things YOU chose (not dependencies)
brew leaves --installed-on-request

# 2. Pick one you don't recognize, e.g. "figlet". Confirm nothing needs it:
brew uses --installed figlet     # empty output = safe

# 3. Remove it, then sweep up any dependencies it leaves orphaned
brew uninstall figlet
brew autoremove

# 4. Reclaim the disk space
brew cleanup

Never remove something that brew uses --installed reports as needed. And don't manually delete dependencies — let brew autoremove decide. It removes a dependency only when no package you chose still relies on it.

Back up your setup first. brew bundle dump writes a Brewfile listing everything you have. On a new Mac (or after over-zealous cleanup), brew bundle reinstalls it all in one shot. Worth keeping in your dotfiles.

08Quick Reference

Every command in this guide, in one scannable table.

Command	What it does
brew install <x>	Install a CLI tool (formula)
brew install --cask <x>	Install a GUI app or font
brew search <x>	Find packages by name/keyword
brew desc <x>	One-line description
brew info <x>	Full details: version, deps, caveats, size
brew home <x>	Open the project's website
brew deps <x>	What this package needs
brew deps --tree <x>	...as a nested tree
brew uses --installed <x>	What needs this (empty = safe to remove)
brew leaves --installed-on-request	Only the things you chose
brew list --formula	Every installed formula
brew list --cask	Every installed GUI app/font
which <x> · type <x>	Is it a command? where? (reveals aliases)
tldr <x> · man <x>	Usage examples / full manual
brew uninstall <x>	Remove a package
brew autoremove	Remove orphaned dependencies
brew cleanup	Delete old versions & cache (-n to preview)
brew update	Refresh Homebrew & package catalog
brew outdated	What has newer versions available
brew upgrade [<x>]	Upgrade everything (or just one)
brew doctor	Diagnose problems
brew services list	Status of background services
brew bundle dump	Write a Brewfile backup of your setup