Skip to content


Repository files navigation

Homebrew Bundle

Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store, Whalebrew and Visual Studio Code.


Homebrew (on macOS or Linux) for installing dependencies.

Homebrew Cask is optional and used for installing Mac applications.

mas-cli is optional and used for installing Mac App Store applications.

Whalebrew is optional and used for installing Whalebrew images.

Visual Studio Code is optional and used for installing Visual Studio Code extensions.


brew bundle is automatically installed when first run.


See the brew bundle section of the brew generate-man-completions output or brew bundle --help.

An example Brewfile:

# 'brew tap'
tap "homebrew/cask"
# 'brew tap' with custom Git URL
tap "user/tap-repo", "https://[email protected]/user/homebrew-tap-repo.git"
# 'brew tap' with arguments
tap "user/tap-repo", "https://[email protected]/user/homebrew-tap-repo.git", force_auto_update: true

# set arguments for all 'brew install --cask' commands
cask_args appdir: "~/Applications", require_sha: true

# 'brew install'
brew "imagemagick"
# 'brew install --with-rmtp', 'brew services restart' on version changes
brew "denji/nginx/nginx-full", args: ["with-rmtp"], restart_service: :changed
# 'brew install', always 'brew services restart', 'brew link', 'brew unlink mysql' (if it is installed)
brew "[email protected]", restart_service: true, link: true, conflicts_with: ["mysql"]
# install only on specified OS
brew "gnupg" if OS.mac?
brew "glibc" if OS.linux?

# 'brew install --cask'
cask "google-chrome"
# 'brew install --cask --appdir=~/my-apps/Applications'
cask "firefox", args: { appdir: "~/my-apps/Applications" }
# bypass Gatekeeper protections (NOT RECOMMENDED)
cask "firefox", args: { no_quarantine: true }
# always upgrade auto-updated or unversioned cask to latest version even if already installed
cask "opera", greedy: true
# 'brew install --cask' only if '/usr/libexec/java_home --failfast' fails
cask "java" unless system "/usr/libexec/java_home", "--failfast"

# 'mas install'
mas "1Password", id: 443_987_910

# 'whalebrew install'
whalebrew "whalebrew/wget"

# 'vscode --install-extension'
vscode "GitHub.codespaces"

Versions and lockfiles

Homebrew is a rolling release package manager so it does not support installing arbitrary older versions of software. If your software needs specific pinned versions, consider whalebrew lines in your Brewfile to install Docker containers.

After a successful brew bundle run, it creates a Brewfile.lock.json to record the environment. If a future brew bundle run fails, you can check the differences between Brewfile.lock.json to debug. As it can contain local environment information that varies between systems, it's not worth committing to version control on multi-user repositories.

Disable generation of the Brewfile.lock.json file by setting the environment variable with export HOMEBREW_BUNDLE_NO_LOCK=1 or by using the command-line argument brew bundle --no-lock.

New Installers/Checkers/Dumpers

brew bundle currently supports Homebrew, Homebrew Cask, Mac App Store, Whalebrew and Visual Studio Code.

We are interested in contributions for other installers/checkers/dumpers but they must:

  • be able to install software without user interaction
  • be able to check if software is installed
  • be able to dump the installed software to a format that can be stored in a Brewfile
  • not require sudo to install
  • be extremely widely used

Note: based on these criteria, we would not accept e.g. Whalebrew (but have no plans to remove it.)


Tests can be run with bundle install && bundle exec rspec. Syntax linting can be run with brew style homebrew/bundle.


Copyright (c) Homebrew maintainers and Andrew Nesbitt. See LICENSE for details.