My HomeBrew cheat sheet


Be aware it's not an exhaustive list.

Permalink to heading Essential concepts Essential concepts

Permalink to heading What’s Homebrew? What’s Homebrew?

Homebrew is a powerful package manager. It can ease your dev significantly, so do no hesitate to try it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Once it’s done, run brew and you should get the help menu to learn the various built-in commands of Homebrew. If so, you can now use a sets of command lines to manage packages on your machine.

Permalink to heading Is Homebrew a Mac-only software? Is Homebrew a Mac-only software?

Not at all, even if there are special configs and extensions for macOS.

Homebrew is available for Linux too. Windows users can use it but only with WSL (the Subsystem for Linux).

Behind the scene, Homebrew makes symlinks, which allows using third-party commands from packages in the terminal easily.

Permalink to heading What are Homebrew Formulae? What are Homebrew Formulae?

A formula is a Ruby script that “provides instructions and metadata for Homebrew to install a piece of software”.

Technically, Homebrew formulae are subclasses of Formula. Homebrew uses them for package definitions.

Permalink to heading What is “cask”? What is “cask”?

You may have seen commands like brew install --cask tor-browser. Homebrew uses cask to deal with various licences and interact with graphical applications.

It’s particularly helpful to install apps from the terminal without having to drag and drop them into the /Applications/ directory.

Technically, cask is an extension of Homebrew but you don’t have to install it manually, it’s already packed with Homebrew.

Permalink to heading What is “tap”? What is “tap”?

Taps are useful to install formulae from alternative sources such as GitHub. When you use brew tap <FORMULA>, Homebrew considers it comes from GitHub by default but you can specify other locations:

brew tap [options] [user/repo] [URL]

Permalink to heading What are bundles? What are bundles?

Bundles handle non-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store and Whalebrew. You can quickly list all bundles with:

brew bundle list

or:

less ~/Brewfile

Technically, bundle is an extension of Homebrew but you don’t have to install it manually, it’s already packed with Homebrew.

It’s a pretty elegant way to install softwares in macOS for engineers.

Permalink to heading Why does homebrew force updates? Why does homebrew force updates?

It’s not uncommon Homebrew updates some packages while you did not run brew update or brew upgrade. For example, when you install a new package, Homebrew analyzes libraries to add/remove required/outdated dependencies and keep things consistent.

Permalink to heading Basic commands Basic commands

Permalink to heading Display all available commands Display all available commands

brew commands

Pretty cool to learn the tool!

Permalink to heading Install a formula Install a formula

brew install <FORMULA>

Permalink to heading Uninstall a formula Uninstall a formula

brew uninstall <FORMULA>

Permalink to heading Display information for a specific formula Display information for a specific formula

brew info <FORMULA>

Permalink to heading Display the homepage of a given formula Display the homepage of a given formula

brew home <FORMULA>

The homepage URL is the one specified in the package’s metadata, for example:

class Git < Formula
  desc "Distributed revision control system"
  homepage "https://git-scm.com"

Permalink to heading Search packages Search packages

brew search <KEYWORD>

Pretty self-explanatory but you can also use regex and interesting options such as --archlinux to restrict your search to a given database.

Permalink to heading List all formulae including casks List all formulae including casks

brew list

You can use brew list --casks to list casks only.

Permalink to heading List available updates List available updates

brew outdated

Permalink to heading Update vs. upgrade Update vs. upgrade

brew update updates the system, including Homebrew itself, whereas brew upgrade only updates installed formulae.

Note that you can also upgrade only a specific formula with brew upgrade <FORMULA>.

Permalink to heading Cleaning stuff Cleaning stuff

You can clean old downloads with the following command:

brew cleanup 

Remove stale lock files and outdated downloads for all formulae and casks, and remove old versions of installed formulae.

It will remove all downloads more than 120 days old by default.

Most of the time, the command is safe to run, but you can use the --dry-run option if you’re not sure to visualize what will be removed instead of running it Yolo.

You can also clean for a specific formula only:

brew cleanup <FORMULA>

Permalink to heading A bit more advanced usages A bit more advanced usages

Permalink to heading Pin / unpin Pin / unpin

pin is used to prevent Homebrew from upgrading a package automatically when running a general update.

brew pin <FORMULA>

Use unpin to remove this exception:

brew unpin <FORMULA>

brew link <FORMULA> allows you to customize symlinks. Use it only when necessary. To delete an existing symlink created with Homebrew, run brew unlink <FORMULA>.

You can also use brew unlink <FORMULA> && brew link <FORMULA> to relink a formula.

Permalink to heading List all taps List all taps

brew tap

Permalink to heading Remove taps Remove taps

brew untap --force <TAP>

Permalink to heading Locate the cache directory Locate the cache directory

brew --cache

Permalink to heading Force cache delete manually Force cache delete manually

rm -rf "$(brew --cache)"

Permalink to heading Troubleshooting: Config vs. doctor Troubleshooting: Config vs. doctor

brew doctor runs a quick diagnosis to spot errors whereas brew config displays Homebrew and system configuration info useful for debugging.

Permalink to heading Expert mode 🥷🏻 Expert mode 🥷🏻

Permalink to heading Install Bundles Install Bundles

brew bundle install

Permalink to heading Export the list of all brew entries Export the list of all brew entries

brew bundle dump

The above command generates a Brewfile you can reuse on other machines. By default, the file is located at the root of the $USER folder but you can specify a custom directory with the --file option.

Permalink to heading mas mas

mas allows installing Mac apps from the App Store directly from the terminal:

brew install mas

All specific mas commands start with mas. All apps installed with mas are listed in the Brewfile.

brew cat <FORMULA>

Permalink to heading Edit a formula Edit a formula

brew edit <FORMULA>

Permalink to heading Enhance display for brew info <FORMULA> Enhance display for brew info <FORMULA>

brew info --json=v1 <FORMULA> | jq .

Permalink to heading Create custom formulae Create custom formulae

You can cook your own formulae:

class MyFormula < Formula
  desc "My Formula"
  homepage "https://mywebsite.com"
  url "https://example.com/foo-0.1.tar.gz"
  sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
  license "MIT"

  # depends_on "cmake" => :build

  def install
    # ENV.deparallelize
    system "./configure", "--disable-debug",
                          "--disable-dependency-tracking",
                          "--disable-silent-rules",
                          "--prefix=#{prefix}"
    # system "cmake", ".", *std_cmake_args
    system "make", "install"
  end

  test do
    system "false"
  end
end