Brewfile: Rebuild Your Mac Dev Setup with brew bundle

What a Brewfile does

Setting up a new Mac by hand means remembering every tool you installed over the years. A Brewfile solves that. It is a plain text list of your Homebrew formulae, casks, taps and even Mac App Store apps, and the brew bundle command installs everything in it. Keep the file in Git and a fresh machine is a few commands away from your usual setup.

This is the natural next step after the Homebrew section of my Mac development environment guide. If you are new to Homebrew itself, start with Homebrew as a package manager on Mac.

Create a Brewfile from what you already have

You do not need to write one from scratch. Homebrew can dump the current state of your machine:

brew bundle dump --file=~/Brewfile

That writes a file listing everything installed. Add --force to overwrite an existing one. Open it and you will see something like this:

tap "homebrew/cask-fonts"
brew "git"
brew "node"
brew "ripgrep"
cask "visual-studio-code"
cask "iterm2"
mas "Xcode", id: 497799835
vscode "ms-python.python"

Each line type means something different:

• tap: an extra repository of formulae.
• brew: a command-line package.
• cask: a Mac app installed from a downloaded bundle.
• mas: an App Store app, which needs the mas tool and a signed-in App Store.
• vscode: a VS Code extension, when the code command is available.

Install everything on a new Mac

Install Homebrew first, copy the Brewfile across, then run:

brew bundle --file=~/Brewfile

Homebrew installs what is missing and skips what is already there, so you can run it again at any time. If you keep the file at ~/.Brewfile, you can run brew bundle --global and skip the path.

Check that your Mac matches the file

Two commands help you spot drift:

brew bundle check --file=~/Brewfile
brew bundle cleanup --file=~/Brewfile

check tells you whether everything in the file is installed. cleanup lists anything installed that is not in the file. By default it only shows the list. Adding --force actually uninstalls those items, so read the list first.

Keep it tidy and useful

• Remove dependencies you did not choose. The dump includes everything Homebrew installed as a dependency of something else. Delete those lines, since Homebrew will bring them back as needed. Keep only what you installed on purpose.
• Add comments. A line like # Containers above a group helps in six months’ time.
• Split by machine. Use Ruby conditions for work-only apps, for example brew "kubectl" if ENV["WORK_MAC"]. The file is Ruby, so simple logic works.
• Pin nothing unless you must. Brewfiles install the current version. If you need a fixed version, use a versioned formula or a different tool.

Put it in Git

Store the Brewfile in a dotfiles repository, then clone it on a new Mac and run the bundle command. A short bootstrap script is enough:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew bundle --file=~/dotfiles/Brewfile

Check the official Homebrew site for the current install command before you copy it into a script.

Common problems with brew bundle

• A cask fails because the app already exists. If you installed an app by dragging it into Applications, Homebrew may refuse to overwrite it. Remove the app first, or add --force to the cask install, then run the bundle again.
• mas lines fail. The Mac App Store tool needs you to be signed in to the App Store, and it can only install apps you have already acquired with your Apple ID.
• It takes a long time. Casks download full apps, so a first run on a new Mac can take a while. Leave it running on a good connection.

Refresh it as you go

The easiest habit is to re-run the dump whenever you install something you plan to keep:

brew bundle dump --force --file=~/dotfiles/Brewfile
git -C ~/dotfiles commit -am "Update Brewfile"

After a year of this you will have a record of your whole toolset, and moving to a new laptop becomes a coffee break rather than a weekend.