brew bundle: Usage, Options & Common CI Errors
brew bundle installs all formulae, casks, and taps declared in a Brewfile.
brew bundle is the declarative way to provision a macOS runner: list dependencies in a Brewfile and install them all at once, which is far more reproducible than a pile of brew install lines.
What it does
brew bundle reads a Brewfile (brew/cask/tap/mas entries) and installs everything in it. brew bundle check reports whether all dependencies are already satisfied - useful as a fast cache-hit gate in CI. The Brewfile is the single source of truth for the runner's toolchain.
Common usage
brew bundle # install from ./Brewfile
brew bundle --file=ci/Brewfile
brew bundle check || brew bundle # install only if needed
brew bundle --no-lock # do not write Brewfile.lock.json
brew bundle dump --force # generate a BrewfileCommon errors in CI
"No Brewfile found" / "Error: No such file or directory" means brew bundle ran from the wrong directory or the path needs --file=. A single failed entry fails the whole run; pin or remove the broken formula. brew bundle writes Brewfile.lock.json by default, which can dirty the git tree in CI - pass --no-lock to suppress it. As with brew install, set HOMEBREW_NO_AUTO_UPDATE=1 to avoid the slow self-update before bundling.
Options
| Flag | What it does |
|---|---|
| --file=<path> | Use a Brewfile at a custom path |
| check | Report whether dependencies are satisfied |
| --no-lock | Do not write Brewfile.lock.json |
| --no-upgrade | Install missing only; do not upgrade existing |
| dump | Generate a Brewfile from installed packages |
Using this in CI
A runner shell is not a login shell. It does not read your dotfiles, it usually has no TTY, and by default it does not stop on the first error, so a failing command in the middle of a multi-line run block can leave the job green.
# make the shell behave the way you assume it does
- name: Build
shell: bash
run: |
set -euo pipefail # exit on error, undefined vars, and pipeline failures
./do-the-thing | tee out.log