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]

If on or off is passed, turn Homebrew’s analytics on or off respectively.

If state is passed, display the current anonymous user behaviour analytics state. Read more at https://docs.brew.sh/Analytics.

If regenerate-uuid is passed, regenerate the UUID used in Homebrew’s analytics.

cat formula

Display the source of formula.

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.

command cmd

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

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.

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.

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

Install formula. Additional options specific to 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]

List all installed formulae.

If formula is provided, summarize 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]

List installed 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 formulae from the specified tap, or from all installed taps if none is provided. This can be useful for debugging issues across all formulae when making significant changes to formula.rb, testing the performance of loading all formulae or to determine if any current formulae have Ruby issues.

reinstall [options] formula

Uninstall and then install formula using the same options it was originally installed with, plus any appended brew formula options.

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.

sh [options]

Start a Homebrew build environment shell. Uses our years-battle-hardened Homebrew build logic to help your ./configure && make && make install or 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.

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 or ~/.zprofile) with: eval $(brew shellenv)

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.

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

unpack [options] formula

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

unpin formula

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

untap tap

Remove a tapped formula repository.

update, up [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]

Upgrade outdated, unpinned formulae using the same options they were originally installed with, plus any appended brew formula options. If formula are specified, upgrade only the given 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. 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]

Display Homebrew’s download cache. See also HOMEBREW_CACHE.

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

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

Summarize 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. Will exit with a non-zero status if any errors are found, which can be useful for implementing pre-commit hooks.

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-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 must also be specified.

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.

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: http://www.rubydoc.info/github/Homebrew/brew/master/Formula

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.

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.

man [options]

Generate Homebrew’s manpages.

prof command

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

pull [options] patch

Get a patch from a GitHub commit or pull request and apply it to Homebrew. Optionally, publish updated bottles for any formulae changed by the patch.

Each patch may be the number of a pull request in homebrew/core, the URL of any pull request or commit on GitHub or a “https://jenkins.brew.sh/job/…” testing job URL.

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.

tap-new 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.

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 OPTIONS

These options are applicable across all sub-commands.

OFFICIAL EXTERNAL COMMANDS

bundle subcommand:

Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask and the Mac App Store. See brew bundle --help.

Homebrew/homebrew-bundle: https://github.com/Homebrew/homebrew-bundle

cask subcommand:

Install macOS applications distributed as binaries. See brew-cask(1).

Homebrew/homebrew-cask: https://github.com/Homebrew/homebrew-cask

services subcommand:

Manage background services with macOS’ launchctl(1) daemon manager. See brew services --help.

Homebrew/homebrew-services: https://github.com/Homebrew/homebrew-services

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:

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

brew-cask(1), 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, Mike McQuaid 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 and Issy Long.

Homebrew’s other current maintainers are Claudia Pellegrino, Rui Chen, Vitor Galvao, Caleb Xu, Gautham Goli, Steven Peters, William Woodruff, Igor Kapkov, Izaak Beekman, Sean Molenaar, Jan Viljanen, Eric Knibbe, Viktor Szakats, Thierry Moisan, Steven Peters, Tom Schoonjans and Issy Long.

Former maintainers with significant contributions include 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