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 -v, many commands print extra debugging information. Note that these flags should only appear after a command.

install formula:

Install formula.

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 surrounded with slashes, then 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 given, all locally available formulae are listed.

COMMANDS

analytics [on|off|state|regenerate-uuid]

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

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

If regenerate-uuid is passed, regenerate 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 formulae and casks, and remove old versions of installed formulae. If arguments are specified, only do this for the specified formulae and casks.

command cmd

Display the path to the file which is used when invoking brew cmd.

commands [options]

Show a list of built-in and external commands.

config

Show Homebrew and system configuration useful for debugging. If you file a bug report, you will likely be asked for this information if you do not provide it.

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. Doctor exits 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 the source packages for the given formula. For tarballs, also print SHA-256 checksums.

gist-logs [options] formula

Upload logs for a failed build of formula to a new Gist.

formula is usually the name of the formula to install, but it can be specified in several different ways.

If no logs are found, an error message is presented.

home [formula]

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

info [options] [formula]

Display brief statistics for your Homebrew installation.

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

install [options] formula

Install formula.

formula is usually the name of the formula to install, but it can be specified in several different ways.

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

leaves

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

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

list, ls [options]

List all installed formulae.

log [options] formula

Show the git log for the given formula.

migrate [options] formula

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

missing [options] [formule]

Check the given formula for missing dependencies. If no formula are given, check all installed brews.

missing exits with a non-zero status if any formulae are missing dependencies.

options [options] formula

Display install options specific to formula

outdated [options]

Show 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 specified tap (defaults to all installed taps). 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 (with existing and any appended install options).

Unless HOMEBREW_NO_INSTALL_CLEANUP is set, brew cleanup will 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 surrounded with slashes, then it is interpreted as a regular expression. The search for text is extended online to homebrew/core and homebrew/cask.

If no text is passed, display 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 otherwise build systems would not find.

shellenv

Prints export statements - run them in a shell and this installation of Homebrew will be included into your PATH, MANPATH and INFOPATH.

HOMEBREW_PREFIX, HOMEBREW_CELLAR and HOMEBREW_REPOSITORY are also exported to save multiple queries of those variables.

Consider adding evaluating the output in your dotfiles (e.g. ~/.profile) 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 specific version of formula’s install to Homebrew prefix.

tap [options] user/repo [URL]

Tap a formula repository.

List all installed taps when no arguments are passed.

With URL unspecified, taps 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, taps a formula repository from anywhere, using any transport protocol that git 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]

Display detailed information about one or more provided tap. Display a brief summary of all installed taps if no tap are passed.

uninstall, rm, remove [options] formula

Uninstall formula.

Remove symlinks for formula from the Homebrew 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 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]

Fetches and resets 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 (with existing and any appended brew formula options).

If formula are given, upgrade only the specified brews (unless they are pinned; see pin, unpin).

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

uses [options] formula

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

By default, uses shows usage of formula by 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]

Show a summary of the Homebrew 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 [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 number of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask (if tapped) to standard output and exit.

DEVELOPER COMMANDS

audit [options] formula

Check formula for Homebrew coding style violations. This should be run before submitting a new formula. Will exit with a non-zero status if any errors are found, which can be useful for implementing pre-commit hooks. If no formula are provided, all of them are checked.

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 a 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 preexisting formula already uses.

bump-revision [options] [formula]

Create a commit to increment the revision of the 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 a 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 user/repo/formula.

formula formula

Display the path where a formula is located.

irb [options]

Enter the interactive Homebrew Ruby shell.

linkage [options] [formula]

Check the library links for kegs of installed formulae. 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 the formulae changed by the patch.

Each patch may be the number of a PR in homebrew/core, the URL of a PR on GitHub, the URL of a 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]:

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 arguments 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, 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

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 and Issy Long.

Homebrew’s other current maintainers are Claudia Pellegrino, Chongyu Zhu, Vitor Galvao, Gautham Goli, Steven Peters, William Woodruff, Igor Kapkov, Izaak Beekman, Sean Molenaar, Jan Viljanen, Jason Tedor, 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 and Homebrew’s creator: Max Howell.

BUGS

See our issues on GitHub:

Fork me on GitHub