The ultimate Homebrew setup and usage guide.

the-homebrew-guide.md

The Homebrew Guide

The ultimate Homebrew setup and usage guide.

What is Homebrew?

Homebrew is the missing package manager for macOS. It allows you to install command line tools brew install ... as well as GUI desktop apps brew cask install ... all through the command line.

Install Homebrew

curl -fsS 'https://raw.githubusercontent.com/Homebrew/install/master/install' | ruby

Usage

To use Homebrew, we'll need to know a few commands. Find the official documentation here.

• brew doctor - Very important. Brew Doctor will tell you what isn't working with your Homebrew instance. Anytime you install a new package you should be running brew doctor to make sure everything installed correctly or if there are additional steps such as linking, editing your path, or errors occurred.
• brew update - This updates the catalogue of available packages. This should be run before anything you do, often brew will auto update before an install or upgrade.
• brew upgrade - This will upgrade all of your installed packages based on what it can find in the catalogue. Apps must be repackaged and uploaded to the catalogue before you can pull a new version, most maintainers are pretty good about keeping things up to date quickly.
• brew install mypackage - Install a command line tool.
• brew cask install myapp - Install a GUI desktop app.
• brew search mypackage - Searches the catalogue for apps with similar names (when installing packages, you must give the explicit name for the package. Try "google" for instance.
• brew cleanup - Removes all unused/old packages that aren't linked or were left behind from old installs.
• brew link mypackage - Links the package specified. Great for switching between versions. Optionally, use =unlink= to unlink a package.

Install Casks to Home Directory

To install applications with a non-admin account, you'll need to install them in the user's home application directory instead of the global applications directory. This won't require sudo access. Replace "USERNAME" below.

brew cask install myapp --appdir=/Users/USERNAME/Applications

Gotchas

Homebrew is an incredible tool making package management a breeze; however, it is very easy to mess up your Homebrew instance. Please reach out to IT for any help with Homebrew outside the scope of this tutorial.

Paths

Homebrew installs everything to /usr/local which is not on macOS by default. If your Mac continues to use the built in versions of many languages (PHP, Ruby, Python) and you want to have macOS instead use the Homebrew versions, you should do the following. DO NOT remove the built in languages that come with macOS as many built in apps require their presence.

Finding which location is being used

Use the following command to see which Ruby is being used by your terminal. This is useful when trying to determine if the built in macOS Ruby is being used or Homebrew's.

which ruby
#/usr/bin/ruby -- built-in
#/usr/local/opt/ruby/bin/ruby -- Homebrew

Your Paths File - /etc/paths

Your paths file tells your terminal what can be executed and where to look do to so. It should look like the following:

# homebrews should always take precedence
/usr/local/bin

# the default stack
/usr/bin
/bin
/usr/sbin
/sbin

Updating Your Path

If your terminal can't find the Homebrew executables to use, you can append Homebrews path to yours:

echo export PATH=/usr/local/bin:$PATH >> ~/.bash_profile
# if using zsh, use "~/.zshrc" instead