mattia.cloud

Tooling

How to Pin a Homebrew Dependency

How to use Homebrew's pin and unpin commands to control when an installed formula is upgraded.

Mattia Valzelli
Mattia Valzelli Published · 2 min read Last updated
A Homebrew-inspired beer mug beside a software package secured by a push pin.
A Homebrew-inspired beer mug beside a software package secured by a push pin.

Sometimes you need to pin a tool used in a project to a specific version, but not all dependencies are versioned in Homebrew. Homebrew normally keeps installed packages current, but you can temporarily pin one to prevent an upgrade.

This article assumes that you already have Homebrew installed and are familiar with it.

Formulae and versions

Homebrew knows how to install packages by looking at a formula. A formula is a Ruby definition describing a package’s source, dependencies, and installation process. To speed up this process, Homebrew may provide a precompiled package, known as a bottle. You can inspect a formula with brew info, which displays a summary of the formula.

Core formulae are available in the homebrew-core repository; for example, you can look at the curl formula.

Pin an installed formula

The brew pin command prevents Homebrew from upgrading an installed formula, preserving its currently installed version. To pin curl, run:

brew pin curl

Warning

Pinning a formula will prevent it from receiving security updates and bug fixes; be careful when applying pins.

You can check which packages are currently pinned with:

brew list --pinned

Unpin and upgrade a formula

Pins are usually temporary. When you are ready to update the formula, remove the pin with brew unpin, then upgrade it:

brew unpin curl
brew upgrade curl

If you still need to control when the formula is updated, pin it again:

brew pin curl

Installing an older version

You can pin a formula only if it is already installed. Homebrew also provides some formulae for older major or minor versions (with names such as postgresql@18). Supported versioned formulae can continue to receive patch and security updates, so prefer one when available. You can also search to see the available versions:

brew search postgresql@

If the version you need previously existed in homebrew/core but is no longer available as a versioned formula, Homebrew provides brew version-install.

For example, Homebrew’s documentation shows how to recover Automake 1.12:

brew version-install automake@1.12

This extracts the older formula into your own tap, making you responsible for maintaining it and applying security updates.

Use brew pin for a temporary hold on an installed version. Prefer a supported versioned formula when you need an older release, and use brew version-install only when you are prepared to maintain it yourself.