I’ll be using hugo as an example. Let’s say I wanted to install v0.145.0 because v0.146.0 introduced breaking changes that broke my theme.

tl;dr:

To install hugo v0.145.0:

• Create a local tap with brew tap-new $USER/local
• Tap homebrew/core which is a 1.3GB clone at the time of writing
• Extract the formula with brew extract
• Patch the hugo formula. This isn’t needed for every formula.
• Install as usual

Note that this process will point your hugo command to the older version, but you can switch between versions with brew link.

Create a local tap

Run brew tap-new $USER/local

$ brew tap-new $USER/local

Initialized empty Git repository in /opt/homebrew/Library/Taps/nelson/homebrew-local/.git/
[main (root-commit) 6af371f] Create nelson/local tap
 3 files changed, 111 insertions(+)
 create mode 100644 .github/workflows/publish.yml
 create mode 100644 .github/workflows/tests.yml
 create mode 100644 README.md
==> Created nelson/local
/opt/homebrew/Library/Taps/nelson/homebrew-local

When a pull request making changes to a formula (or formulae) becomes green
(all checks passed), then you can publish the built bottles.
To do so, label your PR as `pr-pull` and the workflow will be triggered.

It will enable developer mode. This is normal and safe.

Tap homebrew/core

Next, run brew tap --force homebrew/core. At the time of writing, it’s a 1.3GB download. This is necessary to get this working because Homebrew no longer keeps homebrew-core cloned locally. The brew extract command needs the full git history to search for older versions.

$ brew tap --force homebrew/core

✔︎ JSON API formula.jws.json                                                                                                                                    Downloaded   32.0MB/ 32.0MB
✔︎ JSON API cask.jws.json                                                                                                                                       Downloaded   15.4MB/ 15.4MB
==> Tapping homebrew/core
Cloning into '/opt/homebrew/Library/Taps/homebrew/homebrew-core'...
remote: Enumerating objects: 3385552, done.
remote: Counting objects: 100% (544/544), done.
remote: Compressing objects: 100% (119/119), done.
remote: Total 3385552 (delta 497), reused 427 (delta 425), pack-reused 3385008 (from 4)
Receiving objects: 100% (3385552/3385552), 1.08 GiB | 48.36 MiB/s, done.
Resolving deltas: 100% (2612327/2612327), done.
Tapped 5 commands and 8313 formulae (8,851 files, 1.3GB).

Extract the desired version

Now we can use brew extract. This command will find a commit where the formula was at the version we want and copy that locally as <package>@<version>.rb.

In this case we want Hugo v0.145.0, so we run brew extract --version=0.145.0 hugo $USER/local:

$ brew extract --version=0.145.0 hugo $USER/local

==> Searching repository history
==> Writing formula for hugo at 0.145.0 from revision a110fdb to:
/opt/homebrew/Library/Taps/nelson/homebrew-local/Formula/hugo@0.145.0.rb

Patch the formula

This isn’t needed for every formula and is something I ran into specifically with Hugo. Without this patch, you’ll run into errors.

After running brew extract, edit the file: /opt/homebrew/Library/Taps/$USER/homebrew-local/Formula/hugo@0.145.0.rb.

Change this line:

system "go", "build", *std_go_args(ldflags:, tags:)

To this:

system "go", "build", *std_go_args(output: bin/"hugo", ldflags:, tags:)

The reason we need to patch this file is because it prevents the error:

command not found: /opt/homebrew/Cellar/hugo@0.145.0/0.145.0/bin/hugo

It’s a mismatch between the path Homebrew expects (bin/hugo) vs the path that is created when using brew extract on Hugo (bin/hugo@0.145.0).

Install the older version

Now that Hugo is extracted and patched, we can install with brew install hugo@0.145.0:

$ brew install hugo@0.145.0

✔︎ JSON API cask.jws.json
✔︎ JSON API formula.jws.json
==> Fetching downloads for: hugo@0.145.0
✔︎ Formula hugo@0.145.0 (0.145.0)
==> Installing hugo@0.145.0 from nelson/local
==> go build -o=/opt/homebrew/Cellar/hugo@0.145.0/0.145.0/bin/hugo -tags=extended withdeploy -ldflags=-s -w -X github.com/gohugoio/hugo/common/hugo.commitHash=nelson -X github.com/gohugoio/hugo/common/
==> /opt/homebrew/Cellar/hugo@0.145.0/0.145.0/bin/hugo gen man --dir /opt/homebrew/Cellar/hugo@0.145.0/0.145.0/share/man/man1
Warning: These files were overwritten during the `brew link` step:
/opt/homebrew/etc/bash_completion.d/hugo
.
.
.
/opt/homebrew/share/zsh/site-functions/_hugo

They have been backed up to: /Users/nelson/Library/Caches/Homebrew/Backup
==> Summary
🍺  /opt/homebrew/Cellar/hugo@0.145.0/0.145.0: 53 files, 73MB, built in 8 seconds
==> Running `brew cleanup hugo@0.145.0`...
Disable this behaviour by setting `HOMEBREW_NO_INSTALL_CLEANUP=1`.
Hide these hints with `HOMEBREW_NO_ENV_HINTS=1` (see `man brew`).
==> Caveats
zsh completions have been installed to:
  /opt/homebrew/share/zsh/site-functions

Hugo v0.145.0 is now installed. There’s a warning with long output in the previous example due to the normal Hugo package being already installed but that is expected. Homebrew is now pointing the hugo binary to v0.145.0 instead of the latest version (v0.160.1 at the time of writing). We can verify with hugo version:

$ hugo version

hugo v0.145.0+extended+withdeploy darwin/arm64 BuildDate=2025-02-26T15:41:25Z VendorInfo=brew

We can also see that Hugo v0.145.0 is installed along with the latest version with brew list | grep hugo:

$ brew list | grep hugo

hugo
hugo@0.145.0

Switching Between Versions with brew link

Currently the hugo command is pointing to v0.145.0. To have it point back to the regular version, run brew unlink hugo && brew link --overwrite hugo:

$ brew unlink hugo && brew link --overwrite hugo

Unlinking /opt/homebrew/Cellar/hugo/0.160.1... 2 symlinks removed.
Linking /opt/homebrew/Cellar/hugo/0.160.1... 49 symlinks created.

And if we want hugo to point back to the old version, run brew unlink hugo@0.145.0 && brew link --overwrite hugo@0.145.0

$ brew unlink hugo@0.145.0 && brew link --overwrite hugo@0.145.0

Unlinking /opt/homebrew/Cellar/hugo@0.145.0/0.145.0... 1 symlinks removed.
Linking /opt/homebrew/Cellar/hugo@0.145.0/0.145.0... 48 symlinks created.

At first I expected brew link --overwrite hugo to work right off the bat, but running both brew unlink and brew link --overwrite is necessary to switch between versions properly. This is because Homebrew tracks linked formulas and actual symlinks on disk separately. To help Homebrew track things properly we need to run both brew unlink to clean the records, then brew link --overwrite to write the new symlinks.

There’s no need to use brew pin to prevent the older version of Hugo from updating. Since this is a local copy, there is no remote repository that would be updated that would in turn update our local version. You can even try running brew update to see the warning message:

$ brew update

==> Updating Homebrew...
Warning: No remote 'origin' in /opt/homebrew/Library/Taps/nelson/homebrew-local, skipping update!
Already up-to-date.

Removing the Older Version

If you no longer need Hugo v0.145.0 you can run brew uninstall hugo@0.145.0:

$ brew uninstall hugo@0.145.0

Uninstalling /opt/homebrew/Cellar/hugo@0.145.0/0.145.0... (53 files, 73MB)

If you don’t have any other packages you extracted with brew extract, you can also remove your local tap with brew untap $USER/local

$ brew untap $USER/local

Untapping nelson/local...
Untapped 1 formula (34 files, 36.7KB).

Finally, if you don’t plan on using brew extract again in the future, you can remove the local clone of homebrew-core with brew untap homebrew/core. This will clean up the 1.3GB of files that was downloaded:

$ brew untap homebrew/core

Untapping homebrew/core...
Untapped 5 commands and 8313 formulae (8,975 files, 1.3GB).

Then re-link hugo to the latest version with brew unlink hugo && brew link hugo:

$ brew unlink hugo && brew link hugo

Unlinking /opt/homebrew/Cellar/hugo/0.160.1... 2 symlinks removed.
Linking /opt/homebrew/Cellar/hugo/0.160.1... 49 symlinks created.

References

• https://docs.brew.sh/Manpage
• https://github.com/orgs/Homebrew/discussions/2941
• https://emmer.dev/blog/installing-old-homebrew-formula-versions/

Here’s what my brew leaves output looks like at the time of this writing:

$ brew leaves

automake
bat
black
coreutils
ffmpeg
go
htop
hugo
jq
libksba
libpq
libtool
libyaml
node
openssl@1.1
pkg-config
postgresql@14
python-typing-extensions
tldr
tree
yt-dlp
zlib

In my case, I know I don’t need the libpq package anymore. So I can remove this package and then run brew leaves again to confirm it’s gone.

$ brew remove libpq

Uninstalling /opt/homebrew/Cellar/libpq/16.1_1... (2,380 files, 29.9MB)

$ brew leaves

automake
bat
black
coreutils
ffmpeg
go
htop
hugo
jq
libksba
libtool
libyaml
node
openssl@1.1
pkg-config
postgresql@14
python-typing-extensions
tldr
tree
yt-dlp
zlib

And now libpq is gone! Try out brew leaves yourself. You may be surprised at the amount of things installed that you may not actually need.

References

• https://docs.brew.sh/Manpage#leaves---installed-on-request---installed-as-dependency

Warning: This method is outdated!:

The approach outlined in this post still works in some cases, but as Homebrew has changed, this method has become unreliable. You may run into errors like:

Error: Couldn't find manifest matching bottle checksum.

Error: An exception occurred within a child process:
  NoMethodError: undefined method 'user' for nil

A cleaner approach is brew extract, which copies the historical formula into a local tap so Homebrew has the context it needs. See my newer post instead: How to Install a Specific Version of a Homebrew Package with brew extract.

It’s possible to install older versions of Homebrew packages by saving an older version of the corresponding Ruby file locally and running brew install <package>.rb. I’ll use the terraform package as an example.

tl;dr:

If I wanted to downgrade to Terraform 1.3.6, I would need to:

• Find the Ruby file for that specific version of Terraform on the Homebrew GitHub repo
• Download the Ruby file
• Uninstall the current version of terraform by running brew remove terraform
• Install the older version defined in the Ruby file by running HOMEBREW_DEVELOPER=true brew install --formulae terraform.rb

Let’s say we have terraform version 1.4.5 but we need terraform version 1.3.6. We can start by browsing to https://github.com/Homebrew/homebrew-core/tree/master/Formula and try to find the formula for terraform under the t directory.

Note:

Terraform has since been removed from homebrew-core after its license change, so the blob/master URL no longer exists. I’ll be using a Terraform link pinned to a specific commit hash. For any package that is still in homebrew-core, the URL pattern previously described still applies: https://github.com/Homebrew/homebrew-core/blob/master/Formula/<directory-containing-package>/<package-name>.rb

Since there are a lot of files here, it’s easier to just modify the URL path in the browser. Modify the path based on the directory the command is in: Take the name of the package and append it at the end of the url, adding /<directory-containing-package>/<package-name>.rb to the URL. The .rb is important because all Homebrew packages are defined in Ruby (files with the .rb extension).

In this case, we’ll append /t/terraform.rb to the URL like so: https://github.com/Homebrew/homebrew-core/blob/6785b6baa9a6ce18c8230de9e9f0f847547dda9a/Formula/t/terraform.rb

That URL will then take us to the Ruby file where the terraform Homebrew package is defined.

Next, click the “History” link on the upper right above the code, or just click on this link https://github.com/Homebrew/homebrew-core/commits/master/Formula/t/terraform.rb. In the next page, scroll down until you see the “terraform: update 1.3.6 bottle” link. Note that you may need to click on “Browse History” at the bottom of this page before continuing your search.

Click on the terraform: update 1.3.6 bottle link to see this page:

On the right side above the code block, click on the three dots, then click on “View file”.

This will take you to the package formula for this specific version of terraform.

On the upper right side of the code block, click on “Raw”. This gives us the exact code we need to install Terraform 1.3.6. Save the code locally to a file called terraform.rb. You can manually copy and paste or use curl:

curl https://raw.githubusercontent.com/Homebrew/homebrew-core/169f333f93fe0703b542cdf75b1decd4cb78f68d/Formula/terraform.rb > terraform.rb

Then, remove the existing package:

$ brew remove terraform

Uninstalling /usr/local/Cellar/terraform/1.4.5... (6 files, 69MB)

Then run brew install but specify the file you saved locally to install the older version. Note that as of Homebrew version 4.6.4 you can no longer install formulae directly from a file. You can get around this by specifying the environment variable HOMEBREW_DEVELOPER.

So to install Terraform from the file we just downloaded, run HOMEBREW_DEVELOPER=true brew install --formulae terraform.rb:

$ HOMEBREW_DEVELOPER=true brew install --formulae terraform.rb

==> Fetching downloads for: terraform
✔︎ Bottle Manifest terraform (1.3.6)
✔︎ Bottle terraform (1.3.6)
Warning: terraform 1.5.7 is available and more recent than version 1.3.6.
==> Pouring terraform--1.3.6.arm64_ventura.bottle.tar.gz
🍺  /opt/homebrew/Cellar/terraform/1.3.6: 7 files, 64MB
==> Running `brew cleanup terraform`...
Disable this behaviour by setting `HOMEBREW_NO_INSTALL_CLEANUP=1`.
Hide these hints with `HOMEBREW_NO_ENV_HINTS=1` (see `man brew`).

Now terraform version 1.3.6 is installed!

$ terraform version

Terraform v1.3.6
on darwin_arm64

Pro Tip:

You can pin the current version so it doesn’t upgrade in the future.

brew pin terraform

The next time you run brew upgrade it will be skipped:

$ brew upgrade

Warning: Not upgrading 1 pinned package:
terraform 1.5.7

When you’re ready to upgrade, you can unpin it:

brew unpin terraform

References

• https://docs.brew.sh/Manpage
• https://docs.brew.sh/FAQ#how-do-i-stop-certain-formulae-from-being-updated