Homebrew

This document contains information about Homebrew, a project that packages software so that it can be built on Mac OS X using the "Developer Tools" (or "Xcode Tools") environment provided by Apple.

Homebrew is an alternative to MacPorts and Fink. I have not tested whether Homebrew can co-exist with its competitors on the same system.

Documentation

• Homebrew website (with simple but sufficient installation instructions at the bottom of the page)
• Homebrew FAQ (includes instructions how to uninstall)
• Homebrew installation (detailed installation instructions)

Glossary

Homebrew uses a "fun" nomenclature that revolves around beer. Reading the man page for the first time is slightly surreal, and the fun usually goes away when you urgently fumble for a term that you just can't remember because you are not very familiar with Homebrew. That's when this glossary might come in handy. Also check out Homebrew's own glossary.

brew 

The main command.

bottle 

A precompiled binary for a formula.

cask 

A Mac OS X GUI application installed via Homebrew-Cask (a separate project that extends Homebrew with the subcommand cask).

cellar 

The folder where Homebrew places all of its files. The default is /usr/local/Cellar. The files in /usr/local are just symlinks that point to the cellar.

formula (pl. formulae) 

A Homebrew package.

keg 

A folder in the cellar that contains the files of a formula. As far as I understand, this refers to a version-specific folder, e.g. /usr/local/Cellar/boost/1.55.0.

keg-only 

A formula is installed only into the cellar, i.e. it is not linked into /usr/local. A typical reason for this is that the formula's files would conflict with files already provided by the system. For instance, macOS already contains a version of Python, available at /usr/bin/python, so Homebrew does not provide a symlink /usr/local/bin/python in order not to override the system-provided Python. If you need symlinks the command brew link is the solution - see below for an example.

pouring 

The process of installing a bottle.

tap 

A Git repository with formulae. Homebrew comes with a number of official taps (e.g. homebrew/core, homebrew/games), but it's also possible to add custom taps.

Installation

A prerequisite for installing Homebrew is that Xcode is present on the system. Homebrew will use the Xcode version that is currently configured with

xcode-select

Homebrew's installation process is started with a single command line. It can be found at the bottom of the Homebrew website. At the time of writing the command was this:

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

The script explains what it's going to do before it does it - very neat! Unlike MacPorts or Fink, Homebrew places its stuff in a location that is not completely out of the way of the rest of the system:

/usr/local/bin

The great advantage of placing stuff in that folder is that you don't have to fiddle with the system environment, because /usr/local/bin is already included in the default system PATH.

Operation principles

sudo

Except at the very beginning, when Homebrew needs to slightly modify the access rights of a few /usr/local subfolders, Homebrew does not require the use of sudo. The FAQ has an entry on why, but the basic reasoning is that running a makefile with sudo is dangerous because it might fiddle with stuff in /usr.

Binary vs. source packages

Homebrew attempts to install a pre-compiled binary package (a so-called "bottle") when you install a formula. If there is no bottle, it will compile the formula from source. Bottles are distributed via a SourceForge project and the SourceForge mirror system, Homebrew simply knows where to look.

The cellar

Homebrew installs packages into a prefix folder, the so-called "cellar". The default is

/usr/local/Cellar

Files in /usr/local/bin are merely symlinks that point to the cellar.

A formula can have multiple folders in the cellar, one for each version of the formula. These folders are called "kegs". For instance:

$ ls -l /usr/local/Cellar/boost
total 0
drwxr-xr-x   5 admin  admin   170  3 Jan  2015 1.55.0
drwxr-xr-x   5 admin  admin   170 14 Mai 19:23 1.60.0_2

Taps

A so-called "tap" is a Git repository with formulae. Homebrew comes with a number of official taps (e.g. homebrew/core, homebrew/games), but it's also possible to add custom taps.

A tap is identified by a combination of

• A user name
• A repository name

This is tailored towards GitHub where the top-level entities are users (or organizations) and the second-level entities are Git repositories.

A tap is stored in this path:

/usr/local/Homebrew/Library/Taps/<user-name>/<repository-name>

See the next section "Usage" for examples how to manage taps.

Usage

Update Homebrew and installed packages

brew update
brew upgrade

Check the system for potential problems (e.g. this lists files that were installed to /usr/local without Homebrew):

brew doctor

List all formulae that Homebrew knows about:

brew search

Search for a given formula (only formulae names are searched):

brew search foo      # substring search
brew search /^foo/   # regex search

List formulae:

brew list              # list formulae installed by Homebrew
brew list --unbrewed   # list files installed by something else than Homebrew

Install/uninstall a formula:

brew install foo
brew uninstall foo

See the detailed description of a formula:

brew info foo

Find out which formulae a formula depends on:

brew deps foo

Find out which locally installed packages depend on a package:

brew uses --installed foo

The following examples show Git repositories with formulae, so-called "taps". See the section Taps further up on this page, or consult the man page for more details.

brew tap                   # taps that are currently installed
brew tap --list-official   # official taps (even if they are not installed)
brew tap --list-pinned     # pinned taps (i.e. taps that have higher priority than homebrew/homebrew-core when searching for formulae)
brew tap-info --installed  # more details on installed taps

Install/uninstall a tap:

# Install from GitHub. The repository URL is assumed to be
# https://github.com/<user-name>/homebrew-<repository-name>
brew tap user-name/repository-name

# Install from anywhere else. The URL can use any transport protocol
# that Git can handle. User and repository names must be specified to
# identify the tap locally, but are not used automatically in any way
# to modify the URL.
brew tap user-name/repository-name URL

# Uninstalling does not require an URL, merely the user and repository
# names that were used to install the tap.
brew untap user-name/repository-name

Pin/unpin an installed tap:

brew tap-pin user-name/repository-name
brew tap-unpin user-name/repository-name

A formula may be "keg-only", which means that Homebrew does not create symlinks in the standard subfolders of /usr/local, such as /usr/local/bin, /usr/local/include and /usr/local/lib. The effect is that most tools will not find the formula's files automatically. Formulas are keg-only for good reasons, the typical case being that the formula's files conflict with files already provided by the system. Homebrew does create a link in the non-standard /usr/local/opt for every formula it installs, so you might be able to point your tools (e.g. a compiler) to take the necessary files from there. If all else fails, and you know what you're doing, you can force Homebrew to create the usual symlinks like this:

# Only list files that would be symlinked
brew link --dry-run foo

# Do the real thing
# The --force parameter is necessary for keg-only formulas
# The --overwrite parameter tells Homebrew to overwrite files that already exist
brew link --force foo

# Same pattern for unlinking/disabling a formula
brew unlink --dry-run foo
brew unlink foo