Posted on Sun 01 December 2013

Homebrew: OS X Package Management

After using Debian/Ubuntu during my undergrad, I recently started to make regular use of OS X at work and personally. I was puzzled by the lack of package management tools like apt-get for dpkg or yum for RPM, until I discovered Homebrew, a great open source package manager for OS X.

Package Manager Overview

A package manager is a set of tools that allow users to easily install, upgrade, and remove software packages. Software authors format their projects into packages for different package managers to make it easy to distribute software on a variety of platforms. Package managers free users from needing to custom manage each piece of software they wish to use on their machine.

Package managers like dpkg, RPM, and others have enhanced the GNU/Linux development environment for decades and projects like Fink, MacPorts, and Homebrew have sought to do the same for OS X, to bring it out of the package management dark ages.


Homebrew requires OS X 10.5+ and the Xcode command line tools. Download the latest *.dmg command line tools for your OS version from Apple Developer Downloads. You may need to search for "command line tools" in the left search box. With any luck, this will be the last time you need to download a *.dmg manually.

Run the Homebrew installation script with the following command from your terminal (, xterm, etc.),

ruby -e "$(curl -fsSL"

Now check that everything is ok with,

brew doctor                # check everything is ok

If you later change your mind and decide to uninstall Homebrew, you would do,

rm -rf /usr/local/Cellar /usr/local/.git && brew cleanup

Note the messiness of installing Homebrew, with its custom scripts and commands. This is the typical software installation experience without a package manager and it is exactly what package managers like Homebrew improve upon.

The installation command sets up Homebrew under usr/local since many programs require dependencies to be located there and also so that sudo permissions are not needed to install Homebrew or packages.

Homebrew packages are called kegs (themed names are a Ruby obsession for some reason) and they are isolated from one another inside their own auto-created directories under /usr/local/Cellar. Homebrew places symbolic links to package executables inside a bin directory /usr/local/bin. By default, this bin directory path should be at the end of your PATH, but you probably want to prepend it to your PATH to prefer Homebrew packages over system defaults (which are frequently out of date).

echo -e "\n# Homebrew bin dir path." >> ${HOME}/.bash_profile
echo "PATH=/usr/local/bin:\$PATH" >> ${HOME}/.bash_profile

All subsequent shells you open will have the updated PATH environment variable. If you want to start using Homebrew installed packages right now,

source ~/.bash_profile

to update PATH in your current shell. Running the brew command should now show some usage examples. If not, consult the Homebrew wiki or troubleshooting guide.


brew list                  # list all installed packages
brew search partial-name   # search for available packages
brew info pkg-name         # get information about a package
brew install/uninstall pkg # install/uninstall a package

Staying up to date

Since Homebrew is actively being developed and community members are constantly adding new packages (formulae) you'll want to keep Homebrew and your package lists up to date.

brew update                # update package lists and Homebrew
brew upgrade               # upgrade packages you have installed
brew upgrade pkg-name      # upgrade a specific package

Behind the scenes, when you installed Homebrew, it made usr/local a version controlled Git repository. Homebrew and its packages are maintained in source so running brew update is pulling the latest Homebrew commits from Github. Try it for yourself,

cd /usr/local              # the home of Homebrew
git logs                   # check Homebrew logs

This also means you are free to branch your Homebrew repo, develop new package formulae, push your fork to Github, and create a pull request!


Homebrew maintains additional Git repos (inside usr/local/Library/Taps) that describe sets of package formulae that are available for installation. Homebrew calls these repos taps to continue its naming theme. The 'mxcl/master' tap is the primary tap you get by default with Homebrew and it describes all the packages that are available with vanilla Homebrew. You can add any other taps you like to have extra packages available at your fingertips.

brew tap                   # list tapped repositories
brew tap tapname           # add tap
brew untap tapname         # remove a tap

As we'll see next, the homebrew-cask tap caskroom/homebrew-cask is one of the most useful taps.

Going Further

So you're comfortable using Homebrew. Great! Have you noticed that Homebrew doesn't always have what you're looking for, things like Google Chrome, Sublime Text, etc.? Do you sometimes download *.dmg files and drag a silly icon to your Applications? I'd recommend you check out homebrew-cask, an open source tap for Homebrew that lets you use the command line to install applications (frequently GUI applications) that are distributed as binaries. Check the homebrew-cask README for installation and usage instructions.


This post serves as a Homebrew primer and reference. If you find any errors or have any suggestions, please kindly contact me at @dghubble or by email at I'll try to keep this updated for reference.

Vote on HN

© Dalton Hubble 2013. Built using Pelican. Theme by @dghubble and source on Github.