How to run multiple versions of Hugo on macOS, part 1: Tarballs

November 19, 2019  ·  3 minute read

Run legacy versions of Hugo to support older projects through the magic of tarballs, aliases, and hopping through a few security loops.

Note: this article is part of our side project, Hugo For Developers.

Hugo, one of the most popular open-source frameworks for building websites, is in rapid development as the release notes show. It’s unusual to find a breaking change, but we’ve encountered a few instances of older sites that won’t build in newer versions of Hugo. So the question becomes, how can we run multiple versions of Hugo at the same time?

Don’t brew on it

Homebrew, the missing package manager for macOS, makes installation as easy as pie:

brew install hugo

Checking your currently installed version is straightforward:

brew info hugo

And updating to the latest and greatest is just as easy:

brew update
brew upgrade hugo
brew cleanup hugo

But as Fernando Medina Corey wrote in Using Legacy Versions of the Hugo Static Site Generator, it’s a little tougher to downgrade in brew, without specific homebrew-core package URLs.

Install Hugo via tarball—then knead until ready

“This gives you the flexibility to have multiple versions on your computer," the Hugo install documentation notes. It’s as simple as downloading the correct binary, dropping it in the right location locally, naming a route to it, and handling some recent Catalina security prompts.

Head to https://github.com/gohugoio/hugo/releases, and find the release version you want. Open the Assets drop-down, and navigate to the macOS versions.

32- or 64-bit? MacWorld has a tidy article on that: Catalina requires 64-bit.

Extended or not? The extended version comes with a SASS compiler.

Download your selected binary — by default, it goes to your Downloads folder.

In terminal, navigate to /usr/local/bin

Create a directory for this version of Hugo. Name it something sensible, like “Hugo-0.57.2”.

In your terminal, cd to your newly created Hugo-version folder, and run

tar zxf ~/Downloads/hugo_0.57.2_macOS-64bit.tar.gz

Or whatever your selected tarball name is. This unpacks the binary. But it’s not executable yet: you’ll get a security notice if you try

./hugo version

This is easy to work around: you can open a Mac app from an unidentified developer via the Finder, and henceforth you won’t see the warning. Control-click on the app, and click through the confirmation warning.

Confirm it’s working from the command line now:

./hugo version

Finally, we’ll want to set up an easy way to call this version via a shell config file alias. cd to your home directory, and edit your shell config file to include the line like

alias hugo57='/usr/local/bin/hugo-0.57.2/hugo'

Save and exit. Test your new versioned hugo command:

hugo57 version
should show you what you expect. Use your new alias everywhere you’d normally use hugo: alias-name server will run the server, for example.

In the next article, we’ll consider another method: asdf-vm helps developers manage multiple runtime versions with a single CLI tool. Maybe we can bundle hugo to the project folder?