brew(1) – The Missing Package Manager for macOS (or Linux)

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. It can also install software not packaged for your Linux distribution to your home directory without requiring sudo.

TERMINOLOGY

formula: Homebrew package definition built from upstream sources

cask: Homebrew package definition that installs macOS native applications

keg: installation destination directory of a given formula version e.g. /usr/local/Cellar/foo/0.1

rack: directory containing one or more versioned kegs e.g. /usr/local/Cellar/foo

keg-only: a formula is keg-only if it is not symlinked into Homebrew’s prefix (e.g. /usr/local)

cellar: directory containing one or more named racks e.g. /usr/local/Cellar

Caskroom: directory containing one or more named casks e.g. /usr/local/Caskroom

external command: brew subcommand defined outside of the Homebrew/brew GitHub repository

tap: directory (and usually Git repository) of formulae, casks and/or external commands

bottle: pre-built keg poured into the cellar/rack instead of building from upstream sources

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.

autoremove [--dry-run]

Uninstall formulae that were only installed as a dependency of another formula and are now no longer needed.

casks

List all locally installable casks including short names.

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 [--quiet] [--include-aliases]

Show lists of built-in and external commands.

completions [subcommand]

Control whether Homebrew automatically links external tap shell completion files. Read more at https://docs.brew.sh/Shell-Completion.

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

brew completions (link|unlink)
Link or unlink Homebrew’s completions.

config, --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|cask …]

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] formula|text|/regex/ […]

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.

developer [subcommand]

Control Homebrew’s developer mode. When developer mode is enabled, brew update will update Homebrew to the latest commit on the master branch instead of the latest stable version along with some other behaviour changes.

brew developer [state]
Display the current state of Homebrew’s developer mode.

brew developer (on|off)
Turn Homebrew’s developer mode on or off respectively.

doctor, dr [--list-checks] [--audit-debug] [diagnostic_check …]

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|cask […]

Download a bottle (if available) or source packages for formulae and binaries for casks. For files, also print SHA-256 checksums.

formulae

List all locally installable formulae including short names.

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, homepage [--formula] [--cask] [formula|cask …]

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

info, abv [options] [formula|cask …]

Display brief statistics for your Homebrew installation.

If a formula or cask is provided, show summary of information about it.

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 [--installed-on-request] [--installed-as-dependency]

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] [installed_formula|installed_cask …]

List all installed formulae and casks.

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

log [options] [formula|cask]

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

migrate [--force] [--dry-run] installed_formula […]

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

missing [--hide=] [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 installed_formula […]

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

postinstall installed_formula […]

Rerun the post-install steps for formula.

readall [--aliases] [--syntax] [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, -S [options] text|/regex/ […]

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.

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. The variable HOMEBREW_SHELLENV_PREFIX will be exported to avoid adding duplicate entries to the environment variables. Consider adding evaluation of this command’s output to your dotfiles (e.g. ~/.profile, ~/.bash_profile, or ~/.zprofile) with: eval "$(brew shellenv)"

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 [--installed] [--json] [tap …]

Show detailed information about one or more taps.

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

uninstall, remove, rm [options] installed_formula|installed_cask […]

Uninstall a formula or cask.

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 installed_formula […]

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

untap [--force] 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/HEAD.

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

upgrade [options] [outdated_formula|outdated_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 and casks that specify formula as a dependency; that is, show dependents of formula. When given multiple formula arguments, show the intersection of formulae that use formula. By default, uses shows all formulae and casks 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, environment [--shell=] [--plain] [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 [--unbrewed] [--installed] [formula …]

Display Homebrew’s install path. Default:

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

--repository, --repo [tap …]

Display where Homebrew’s git repository is located.

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

--version, -v

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

DEVELOPER COMMANDS

audit [options] [formula|cask …]

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

bottle [options] installed_formula|file […]

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|cask …]

Display out-of-date brew formulae and the latest version available. If the returned current and livecheck versions differ or when querying specific formulae, 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 […]

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

bump-unversioned-casks [options] cask|tap […]

Check all casks with unversioned URLs in a given tap for updates.

cat [--formula] [--cask] formula|cask

Display the source of a formula or cask.

command command […]

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

create [options] URL

Generate a formula or, with --cask, a cask 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 […]

Build bottles for these formulae with GitHub Actions.

edit [options] [formula|cask …]

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

extract [--version=] [--force] formula tap

Look through repository history to find the most recent version of formula and create a copy in tap. Specifically, the command will create the new formula file at 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.

generate-man-completions [--fail-if-not-changed]

Generate Homebrew’s manpages and shell completions.

install-bundler-gems [--groups=]

Install Homebrew’s Bundler gems.

irb [--examples] [--pry]

Enter the interactive Homebrew Ruby shell.

linkage [options] [installed_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, lc [options] [formula|cask …]

Check for newer versions of formulae and/or casks from upstream.

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

pr-automerge [options]

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

pr-publish [options] pull_request […]

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

pr-pull [options] 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 a host.

prof [--stackprof] command […]

Run Homebrew with a Ruby profiler. For example, brew prof readall.

release [--major] [--minor]

Create a new draft Homebrew/brew release with the appropriate version number and release notes.

By default, brew release will bump the patch version number. Pass --major or --minor to bump the major or minor version numbers, respectively. The command will fail if the previous major or minor release was made less than one month ago.

Requires write access to the Homebrew/brew repository.

rubocop

Installs, configures and runs Homebrew’s rubocop.

ruby [options] (-e text|file)

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

sh [--env=] [--cmd=] [file]

Enter an interactive shell for Homebrew’s build environment. Use 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

Update the list of GitHub Sponsors in the Homebrew/brew README.

style [options] [file|tap|formula|cask …]

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] installed_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, tc [options]

Check for typechecking errors using Sorbet.

unbottled [options] [formula …]

Show the unbottled dependents of formulae.

unpack [options] formula […]

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

update-license-data [--fail-if-not-changed]

Update SPDX license data in the Homebrew repository.

update-maintainers

Update the list of maintainers in the Homebrew/brew README.

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 [--update=]

Install and commit Homebrew’s vendored gems.

GLOBAL CASK OPTIONS

These options are applicable to the install, reinstall, and upgrade subcommands with the --cask flag.

GLOBAL OPTIONS

These options are applicable across multiple subcommands.

OFFICIAL EXTERNAL COMMANDS

alias [alias … | alias=command]

Show existing aliases. If no aliases are given, print the whole list.

autoupdate subcommand [interval] [options]

An easy, convenient way to automatically update Homebrew.

This script will run brew update in the background once every 24 hours (by default) until explicitly told to stop, utilising launchd.

brew autoupdate start [interval] [options]
Start autoupdating either once every interval hours or once every 24 hours. Please note the interval has to be passed in seconds, so 12 hours would be brew autoupdate start 43200. Pass --upgrade or --cleanup to automatically run brew upgrade and/or brew cleanup respectively. Pass --enable-notification to send a notification when the autoupdate process has finished successfully.

brew autoupdate stop
Stop autoupdating, but retain plist & logs.

brew autoupdate delete
Cancel the autoupdate, delete the plist and logs.

brew autoupdate status
Prints the current status of this tool.

brew autoupdate version
Output this tool’s current version, and a short changelog.

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 specify the Brewfile location using --file or by setting the HOMEBREW_BUNDLE_FILE environment variable.

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 in the current directory.

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 the 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.

command-not-found-init

Print instructions for setting up the command-not-found hook for your shell. If the output is not to a tty, print the appropriate handler script for your shell.

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 set up 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.

unalias alias […]

Remove aliases.

which-formula [--explain] command […]

Prints the formula(e) which provides the given command.

which-update [options] [database]

Database update for brew which-formula

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.

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 Issy Long, Jonathan Chang, Markus Reiter, Misty De Meo and Sean Molenaar.

Homebrew’s Technical Steering Committee is Bo Anderson, FX Coudert, Michka Popoff, Mike McQuaid and Rylan Polster.

Homebrew’s Linux maintainers are Daniel Nachun, Dawid Dziurla, Issy Long, Jonathan Chang, Michka Popoff and Shaun Jackman.

Homebrew’s other current maintainers are Alexander Bayandin, Bevan Kay, Branch Vincent, Caleb Xu, Carlo Cabrera, Connor Mann, Dustin Rodrigues, Eric Knibbe, George Adams, Maxim Belkin, Miccal Matthews, Michael Cho, Nanda H Krishna, Randall, Sam Ford, Steve Peters, Thierry Moisan, Tom Schoonjans, Vítor Galvão and rui.

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