brew(1) – The Missing Package Manager for macOS

SYNOPSIS

brew --version
brew command [--verbose|-v] [options] [formula] …

DESCRIPTION

Homebrew is the easiest and most flexible way to install the UNIX tools Apple didn’t include with macOS.

ESSENTIAL COMMANDS

For the full command list, see the COMMANDS section.

With --verbose or --debug, many commands print extra debugging information. Note that these options should only appear after a command.

install formula:

Install formula.

formula is usually the name of the formula to install, but it has other syntaxes which are listed in the SPECIFYING FORMULAE section.

uninstall formula:

Uninstall formula.

list:

List all installed formulae.

search (text|/text/):

Perform a substring search of cask tokens and formula names for text. If text is flanked by slashes, it is interpreted as a regular expression. The search for text is extended online to homebrew/core and homebrew/cask. If no search term is provided, all locally available formulae are listed.

COMMANDS

analytics [subcommand]

Control Homebrew’s anonymous aggregate user behaviour analytics. Read more at https://docs.brew.sh/Analytics.

brew analytics [state]: Display the current state of Homebrew’s analytics.

brew analytics [on|off]: Turn Homebrew’s analytics on or off respectively.

brew analytics regenerate-uuid: Regenerate the UUID used for Homebrew’s analytics.

cask command [options] [cask]

Homebrew Cask provides a friendly CLI workflow for the administration of macOS applications distributed as binaries.

Commands:

See also: man brew

cleanup [options] [formula|cask]

Remove stale lock files and outdated downloads for all formulae and casks, and remove old versions of installed formulae. If arguments are specified, only do this for the given formulae and casks. Removes all downloads more than 120 days old. This can be adjusted with HOMEBREW_CLEANUP_MAX_AGE_DAYS.

commands [options]

Show lists of built-in and external commands.

config

Show Homebrew and system configuration info useful for debugging. If you file a bug report, you will be required to provide this information.

deps [options] [formula]

Show dependencies for formula. Additional options specific to formula may be appended to the command. When given multiple formula arguments, show the intersection of dependencies for each formula.

desc [options] (text|/text/|formula)

Display formula’s name and one-line description. Formula descriptions are cached; the cache is created on the first search, making that search slower than subsequent ones.

doctor [options]

Check your system for potential problems. Will exit with a non-zero status if any potential problems are found. Please note that these warnings are just used to help the Homebrew maintainers with debugging if you file an issue. If everything you use Homebrew for is working fine: please don’t worry or file an issue; just ignore this.

fetch [options] formula

Download a bottle (if available) or source packages for formula. For tarballs, also print SHA-256 checksums.

gist-logs [options] formula

Upload logs for a failed build of formula to a new Gist. Presents an error message if no logs are found.

home [formula]

Open formula’s homepage in a browser, or open Homebrew’s own homepage if no formula is provided.

info [options] [formula]

Display brief statistics for your Homebrew installation.

If formula is provided, show summary of information about formula.

install [options] formula|cask

Install a formula or cask. Additional options specific to a formula may be appended to the command.

Unless HOMEBREW_NO_INSTALL_CLEANUP is set, brew cleanup will then be run for the installed formulae or, every 30 days, for all formulae.

leaves

List installed formulae that are not dependencies of another installed formula.

Symlink all of formula’s installed files into Homebrew’s prefix. This is done automatically when you install formulae but can be useful for DIY installations.

list, ls [options] [formula|cask]

List all installed formulae or casks

If formula is provided, summarise the paths within its current keg.

log [options] [formula]

Show the git log for formula, or show the log for the Homebrew repository if no formula is provided.

migrate [options] formula

Migrate renamed packages to new names, where formula are old names of packages.

missing [options] [formula]

Check the given formula kegs for missing dependencies. If no formula are provided, check all kegs. Will exit with a non-zero status if any kegs are found to be missing dependencies.

options [options] [formula]

Show install options specific to formula.

outdated [options] [formula|cask]

List installed casks and formulae that have an updated version available. By default, version information is displayed in interactive shells, and suppressed otherwise.

pin formula

Pin the specified formula, preventing them from being upgraded when issuing the brew upgrade formula command. See also unpin.

postinstall formula

Rerun the post-install steps for formula.

readall [options] [tap]

Import all items from the specified tap, or from all installed taps if none is provided. This can be useful for debugging issues across all items when making significant changes to formula.rb, testing the performance of loading all items or checking if any current formulae/casks have Ruby issues.

reinstall [options] formula|cask

Uninstall and then reinstall a formula or cask using the same options it was originally installed with, plus any appended options specific to a formula.

Unless HOMEBREW_NO_INSTALL_CLEANUP is set, brew cleanup will then be run for the reinstalled formulae or, every 30 days, for all formulae.

search [options] [text|/text/]

Perform a substring search of cask tokens and formula names for text. If text is flanked by slashes, it is interpreted as a regular expression. The search for text is extended online to homebrew/core and homebrew/cask.

If no text is provided, list all locally available formulae (including tapped ones). No online search is performed.

shellenv

Print export statements. When run in a shell, this installation of Homebrew will be added to your PATH, MANPATH, and INFOPATH.

The variables HOMEBREW_PREFIX, HOMEBREW_CELLAR and HOMEBREW_REPOSITORY are also exported to avoid querying them multiple times. Consider adding evaluation of this command’s output to your dotfiles (e.g. ~/.profile, ~/.bash_profile, or ~/.zprofile) with: eval $(brew shellenv)

switch formula version

Symlink all of the specified version of formula’s installation into Homebrew’s prefix.

tap [options] [user/repo] [URL]

Tap a formula repository.

If no arguments are provided, list all installed taps.

With URL unspecified, tap a formula repository from GitHub using HTTPS. Since so many taps are hosted on GitHub, this command is a shortcut for brew tap user/repo https://github.com/user/homebrew-repo.

With URL specified, tap a formula repository from anywhere, using any transport protocol that git(1) handles. The one-argument form of tap simplifies but also limits. This two-argument command makes no assumptions, so taps can be cloned from places other than GitHub and using protocols other than HTTPS, e.g. SSH, git, HTTP, FTP(S), rsync.

tap-info [options] [tap]

Show detailed information about one or more taps.

If no tap names are provided, display brief statistics for all installed taps.

uninstall, rm, remove [options] formula

Uninstall formula.

Remove symlinks for formula from Homebrew’s prefix. This can be useful for temporarily disabling a formula: brew unlink formula && commands && brew link formula

unpin formula

Unpin formula, allowing them to be upgraded by brew upgrade formula. See also pin.

untap tap

Remove a tapped formula repository.

update [options]

Fetch the newest version of Homebrew and all formulae from GitHub using git(1) and perform any necessary migrations.

update-reset [repository]

Fetch and reset Homebrew and all tap repositories (or any specified repository) using git(1) to their latest origin/master.

Note: this will destroy all your uncommitted or committed changes.

upgrade [options] [formula|cask]

Upgrade outdated casks and outdated, unpinned formulae using the same options they were originally installed with, plus any appended brew formula options. If cask or formula are specified, upgrade only the given cask or formula kegs (unless they are pinned; see pin, unpin).

Unless HOMEBREW_NO_INSTALL_CLEANUP is set, brew cleanup will then be run for the upgraded formulae or, every 30 days, for all formulae.

uses [options] formula

Show formulae that specify formula as a dependency (i.e. show dependents of formula). When given multiple formula arguments, show the intersection of formulae that use formula. By default, uses shows all formulae that specify formula as a required or recommended dependency for their stable builds.

--cache [options] [formula|cask]

Display Homebrew’s download cache. See also HOMEBREW_CACHE.

If formula is provided, display the file or directory used to cache formula.

--caskroom [cask]

Display Homebrew’s Caskroom path.

If cask is provided, display the location in the Caskroom where cask would be installed, without any sort of versioned directory as the last path.

--cellar [formula]

Display Homebrew’s Cellar path. Default: $(brew --prefix)/Cellar, or if that directory doesn’t exist, $(brew --repository)/Cellar.

If formula is provided, display the location in the Cellar where formula would be installed, without any sort of versioned directory as the last path.

--env [options] [formula]

Summarise Homebrew’s build environment as a plain list.

If the command’s output is sent through a pipe and no shell is specified, the list is formatted for export to bash(1) unless --plain is passed.

--prefix [formula]

Display Homebrew’s install path. Default: /usr/local on macOS and /home/linuxbrew/.linuxbrew on Linux.

If formula is provided, display the location in the Cellar where formula is or would be installed.

--repository, --repo [user/repo]

Display where Homebrew’s .git directory is located.

If user/repo are provided, display where tap user/repo’s directory is located.

--version

Print the version numbers of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask (if tapped) to standard output.

DEVELOPER COMMANDS

audit [options] [formula]

Check formula for Homebrew coding style violations. This should be run before submitting a new formula. If no formula are provided, check all locally available formulae and skip style checks. Will exit with a non-zero status if any errors are found.

bottle [options] formula

Generate a bottle (binary package) from a formula that was installed with --build-bottle. If the formula specifies a rebuild version, it will be incremented in the generated DSL. Passing --keep-old will attempt to keep it at its original value, while --no-rebuild will remove it.

bump [options] [formula]

Display out-of-date brew formulae and the latest version available. Also displays whether a pull request has been opened with the URL.

bump-cask-pr [options] [cask]

Create a pull request to update cask with a new version.

A best effort to determine the SHA-256 will be made if the value is not supplied by the user.

bump-formula-pr [options] [formula]

Create a pull request to update formula with a new URL or a new tag.

If a URL is specified, the SHA-256 checksum of the new download should also be specified. A best effort to determine the SHA-256 and formula name will be made if either or both values are not supplied by the user.

If a tag is specified, the Git commit revision corresponding to that tag should also be specified. A best effort to determine the revision will be made if the value is not supplied by the user.

If a version is specified, a best effort to determine the URL and SHA-256 or the tag and revision will be made if both values are not supplied by the user.

Note: this command cannot be used to transition a formula from a URL-and-SHA-256 style specification into a tag-and-revision style specification, nor vice versa. It must use whichever style specification the formula already uses.

bump-revision [options] formula [formula …]

Create a commit to increment the revision of formula. If no revision is present, “revision 1” will be added.

cat formula

Display the source of formula.

command cmd

Display the path to the file being used when invoking brew cmd.

create [options] URL

Generate a formula for the downloadable file at URL and open it in the editor. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you’ll have to make your own template. The wget formula serves as a simple example. For the complete API, see: https://rubydoc.brew.sh/Formula

dispatch-build-bottle [options] formula [formula …]

Build bottles for these formulae with GitHub Actions.

diy [options]

Automatically determine the installation prefix for non-Homebrew software. Using the output from this command, you can install your own software into the Cellar and then link it into Homebrew’s prefix with brew link.

edit [formula]

Open formula in the editor set by EDITOR or HOMEBREW_EDITOR, or open the Homebrew repository for editing if no formula is provided.

extract [options] formula tap

Look through repository history to find the most recent version of formula and create a copy in tap/Formula/formula@version.rb. If the tap is not installed yet, attempt to install/clone the tap before continuing. To extract a formula from a tap that is not homebrew/core use its fully-qualified form of user/repo/formula.

formula formula

Display the path where formula is located.

install-bundler-gems

Install Homebrew’s Bundler gems.

irb [options]

Enter the interactive Homebrew Ruby shell.

linkage [options] [formula]

Check the library links from the given formula kegs. If no formula are provided, check all kegs. Raises an error if run on uninstalled formulae.

livecheck [formulae]

Check for newer versions of formulae from upstream.

If no formula argument is passed, the list of formulae to check is taken from HOMEBREW_LIVECHECK_WATCHLIST or ~/.brew_livecheck_watchlist.

man [options]

Generate Homebrew’s manpages.

pr-automerge [options]

Find pull requests that can be automatically merged using brew pr-publish.

pr-publish [options] pull_request [pull_request …]

Publish bottles for a pull request with GitHub Actions. Requires write access to the repository.

pr-pull [options] pull_request [pull_request …]

Download and publish bottles, and apply the bottle commit from a pull request with artifacts generated by GitHub Actions. Requires write access to the repository.

pr-upload [options]

Apply the bottle commit and publish bottles to Bintray or GitHub Releases.

prof [command]

Run Homebrew with a Ruby profiler, e.g. brew prof readall.

release-notes [options] [previous_tag] [end_ref]

Print the merged pull requests on Homebrew/brew between two Git refs. If no previous_tag is provided it defaults to the latest tag. If no end_ref is provided it defaults to origin/master.

ruby (-e text|file)

Run a Ruby instance with Homebrew’s libraries loaded, e.g. brew ruby -e "puts :gcc.f.deps" or brew ruby script.rb.

sh [options] [file]

Homebrew build environment that uses years-battle-hardened build logic to help your ./configure && make && make install and even your gem install succeed. Especially handy if you run Homebrew in an Xcode-only configuration since it adds tools like make to your PATH which build systems would not find otherwise.

sponsors

Print a Markdown summary of Homebrew’s GitHub Sponsors, suitable for pasting into a README.

style [options] [file|tap|formula]

Check formulae or files for conformance to Homebrew style guidelines.

Lists of file, tap and formula may not be combined. If none are provided, style will run style checks on the whole Homebrew library, including core code and all formulae.

tap-new [options] user/repo

Generate the template files for a new tap.

test [options] formula

Run the test method provided by an installed formula. There is no standard output or return code, but generally it should notify the user if something is wrong with the installed formula.

Example: brew install jruby && brew test jruby

tests [options]

Run Homebrew’s unit and integration tests.

typecheck

Check for typechecking errors using Sorbet.

unpack [options] formula

Unpack the source files for formula into subdirectories of the current working directory.

update-license-data [options]

Update SPDX license data in the Homebrew repository.

update-python-resources [options] formula

Update versions for PyPI resource blocks in formula.

update-test [options]

Run a test of brew update with a new repository clone. If no options are passed, use origin/master as the start commit.

vendor-gems

Install and commit Homebrew’s vendored gems.

GLOBAL CASK OPTIONS

These options are applicable to subcommands accepting a --cask flag and all cask commands.

GLOBAL OPTIONS

These options are applicable across multiple subcommands.

OFFICIAL EXTERNAL COMMANDS

bundle [subcommand]

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

brew bundle [install]: Install and upgrade (by default) all dependencies from the Brewfile.

You can skip the installation of dependencies by adding space-separated values to one or more of the following environment variables: HOMEBREW_BUNDLE_BREW_SKIP, HOMEBREW_BUNDLE_CASK_SKIP, HOMEBREW_BUNDLE_MAS_SKIP, HOMEBREW_BUNDLE_WHALEBREW_SKIP, HOMEBREW_BUNDLE_TAP_SKIP

brew bundle will output a Brewfile.lock.json in the same directory as the Brewfile if all dependencies are installed successfully. This contains dependency and system status information which can be useful in debugging brew bundle failures and replicating a “last known good build” state. You can opt-out of this behaviour by setting the HOMEBREW_BUNDLE_NO_LOCK environment variable or passing the --no-lock option. You may wish to check this file into the same version control system as your Brewfile (or ensure your version control system ignores it if you’d prefer to rely on debugging information from a local machine).

brew bundle dump: Write all installed casks/formulae/images/taps into a Brewfile.

brew bundle cleanup: Uninstall all dependencies not listed from the Brewfile.

This workflow is useful for maintainers or testers who regularly install lots of formulae.

brew bundle check: Check if all dependencies are installed from the Brewfile .

This provides a successful exit code if everything is up-to-date, making it useful for scripting.

brew bundle list: List all dependencies present in a Brewfile.

By default, only Homebrew dependencies are listed.

brew bundle exec command: Run an external command in an isolated build environment based on the Brewfile dependencies.

This sanitized build environment ignores unrequested dependencies, which makes sure that things you didn’t specify in your Brewfile won’t get picked up by commands like bundle install, npm install, etc. It will also add compiler flags which will help find keg-only dependencies like openssl, icu4c, etc.

services [subcommand]

Manage background services with macOS’ launchctl(1) daemon manager.

If sudo is passed, operate on /Library/LaunchDaemons (started at boot). Otherwise, operate on ~/Library/LaunchAgents (started at login).

[sudo] brew services [list]: List all managed services for the current user (or root).

[sudo] brew services run (formula|--all): Run the service formula without registering to launch at login (or boot).

[sudo] brew services start (formula|--all): Start the service formula immediately and register it to launch at login (or boot).

[sudo] brew services stop (formula|--all): Stop the service formula immediately and unregister it from launching at login (or boot).

[sudo] brew services restart (formula|--all): Stop (if necessary) and start the service formula immediately and register it to launch at login (or boot).

[sudo] brew services cleanup: Remove all unused services.

test-bot [options] [formula]:

Tests the full lifecycle of a Homebrew change to a tap (Git repository). For example, for a GitHub Actions pull request that changes a formula brew test-bot will ensure the system is cleaned and setup to test the formula, install the formula, run various tests and checks on it, bottle (package) the binaries and test formulae that depend on it to ensure they aren’t broken by these changes.

Only supports GitHub Actions as a CI provider. This is because Homebrew uses GitHub Actions and it’s freely available for public and private use with macOS and Linux workers.

CUSTOM EXTERNAL COMMANDS

Homebrew, like git(1), supports external commands. These are executable scripts that reside somewhere in the PATH, named brew-cmdname or brew-cmdname.rb, which can be invoked like brew cmdname. This allows you to create your own commands without modifying Homebrew’s internals.

Instructions for creating your own commands can be found in the docs: https://docs.brew.sh/External-Commands

SPECIFYING FORMULAE

Many Homebrew commands accept one or more formula arguments. These arguments can take several different forms:

SPECIFYING CASKS

Many Homebrew Cask commands accept one or more cask arguments. These can be specified the same way as the formula arguments described in SPECIFYING FORMULAE above.

ENVIRONMENT

Note that environment variables must have a value set to be detected. For example, run export HOMEBREW_NO_INSECURE_REDIRECT=1 rather than just export HOMEBREW_NO_INSECURE_REDIRECT.

export HOMEBREW_CASK_OPTS='--appdir=~/Applications --fontdir=/Library/Fonts'

USING HOMEBREW BEHIND A PROXY

Set the http_proxy, https_proxy, all_proxy, ftp_proxy and/or no_proxy environment variables documented above.

For example, to use an unauthenticated HTTP or SOCKS5 proxy:

export http_proxy=http://$HOST:$PORT

export all_proxy=socks5://$HOST:$PORT

And for an authenticated HTTP proxy:

export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT

SEE ALSO

Homebrew Documentation: https://docs.brew.sh

Homebrew API: https://rubydoc.brew.sh

git(1), git-log(1)

AUTHORS

Homebrew’s Project Leader is Mike McQuaid.

Homebrew’s Project Leadership Committee is Misty De Meo, Shaun Jackman, Jonathan Chang, Sean Molenaar and Markus Reiter.

Homebrew’s Technical Steering Committee is Michka Popoff, FX Coudert, Markus Reiter, Misty De Meo and Mike McQuaid.

Homebrew/brew’s Linux maintainers are Michka Popoff, Shaun Jackman, Dawid Dziurla, Issy Long and Maxim Belkin.

Homebrew’s other current maintainers are Claudia Pellegrino, Zach Auten, Rui Chen, Vitor Galvao, Caleb Xu, Gautham Goli, Steven Peters, Bo Anderson, William Woodruff, Igor Kapkov, Sam Ford, Alexander Bayandin, Izaak Beekman, Eric Knibbe, Viktor Szakats, Thierry Moisan, Steven Peters, Tom Schoonjans, Issy Long, CoreCode, Randall, Rylan Polster, SeekingMeaning, William Ma and Dustin Rodrigues.

Former maintainers with significant contributions include Jan Viljanen, JCount, commitay, Dominyk Tiller, Tim Smith, Baptiste Fontaine, Xu Cheng, Martin Afanasjew, Brett Koonce, Charlie Sharpsteen, Jack Nagel, Adam Vandenberg, Andrew Janke, Alex Dunn, neutric, Tomasz Pajor, Uladzislau Shablinski, Alyssa Ross, ilovezfs, Chongyu Zhu and Homebrew’s creator: Max Howell.

BUGS

See our issues on GitHub:

Fork me on GitHub