Capture packages with a Brewfile

After a few months, a Mac accumulates dozens of Homebrew packages, and nobody remembers why half of them are there. A Brewfile records formulas, casks, taps, and selected other packages in one plain-text file. It makes the intended workstation easier to review and rebuild.

Dump what you have

Create and inspect one deliberately:

brew bundle dump --file Brewfile
brew bundle check --file Brewfile

dump writes the currently installed packages; check confirms everything the file lists is satisfied. The output is readable Ruby-flavored text:

tap "hashicorp/tap"
brew "git"
brew "node"
brew "postgresql@16", restart_service: true
cask "visual-studio-code"
cask "raycast"

brew lines are command-line formulas, cask lines are GUI applications, tap lines are extra package sources.

Now edit it. The dump is a snapshot of what happened to be installed, including experiments you abandoned. Remove accidental personal applications before committing the file — a work setup file that installs your personal chat apps is a smell. What survives the edit is your declared toolchain, and the file belongs in your setup repository where changes show up in diffs and code review.

Rebuild from it

On a new machine, or after pruning:

brew bundle install --file Brewfile
brew bundle check --file Brewfile
# The Brewfile's dependencies are satisfied.

That final line is your verification. There is also brew bundle cleanup --file Brewfile, which lists installed packages the file does not mention — useful as a drift report. It only uninstalls when you add --force, so run it bare first and read the list.

Know what it does not do

brew bundle installs declared software, but it does not restore application data, licenses, credentials, or operating-system settings. Your database contents, your SSH keys, your app preferences: none of that lives in Homebrew’s world.

The realistic failure is treating the Brewfile as a backup, wiping a Mac, and discovering the difference afterward. Treat it as one column of your recovery plan — the “rebuildable” column — and inventory the rest separately, which is exactly what a later module does.