How to Switch Hugo Versions(how to install specific version of Hugo framework on MacOS): Downgrading and Upgrading with Ease

If you’re a developer using Hugo for static site generation, you might have experienced version compatibility issues, especially when newer updates break your existing setup or cause errors. In these cases, reverting to a stable, earlier version often resolves the issues without sacrificing productivity.

Here’s a straightforward guide to downgrading or switching Hugo versions quickly and painlessly:

Why Would You Change Your Hugo Version?

It’s common to want to try out new features or improvements in the latest Hugo release, but sometimes newer versions don’t play nicely with your existing code or dependencies. Typical problems might include:

  • Theme or Module Incompatibility: Some themes or third-party modules might not have updated to support newer Hugo versions.
  • Broken CSS or JS: Changes in the way Hugo processes CSS or JS might cause style issues.
  • Runtime Errors: Unexpected errors during builds or previews could arise from version-specific changes in Hugo’s codebase.

When these kinds of issues pop up, reverting to an earlier, stable version can save time and frustration.

1. Switching Versions via the Command Line

If you’re comfortable with the command line, this method is one of the quickest.

Steps to Downgrade or Change Hugo Versions

  1. Download the Desired Version: Head to the Hugo Releases page on GitHub and download the version you need for your OS.

  2. Install or Extract Hugo: Unzip the downloaded file to a directory you can easily access.

  3. Run the Version Locally: Navigate to the directory where Hugo was extracted and run:

    1

    ./hugo version

    This confirms you’re using the desired version.

  4. Temporarily Add to PATH (Optional): For ease, you can add this version to your PATH temporarily by running:

    1

    export PATH=/path/to/your/hugo/version:$PATH

    This lets you use the hugo command directly without specifying the full path.

  5. Verify the Version:

    1

    hugo version

    You should see the version output to confirm the switch.

2. Managing Versions with Homebrew (macOS/Linux)

If you’re on macOS or Linux, Homebrew is a convenient way to manage multiple versions.

Steps for Homebrew Users

  1. Uninstall Current Version:

    1

    brew uninstall hugo

  2. Install a Specific Version:

    1

    brew install hugo@<version>

    Replace <version> with the exact version number, like hugo@0.92.0.

  3. Link the Installed Version:

    1

    brew link --force hugo@<version>

  4. Verify:

    1

    hugo version

    You should now see the downgraded version in the output.

3. Run Hugo with Docker (Great for Compatibility Testing)

Docker is a fantastic way to test different Hugo versions without installing them directly on your system, especially if you want to test newer or older versions without affecting your local setup.

Steps for Using Docker

  1. Run Hugo with Docker:

    1

    docker run --rm -it -v $(pwd):/src -p 1313:1313 klakegg/hugo:<version> server

    Replace <version> with the Hugo version you want to run, for example, klakegg/hugo:0.92.0.

  2. Verify in Docker: Open a new terminal and check the running Docker containers:

    1

    docker ps

    This confirms that your desired Hugo version is running in a container.

4. Use Version Managers like asdf (Flexible for Multiple Projects)

For developers managing multiple projects, asdf is a version manager that makes it easy to switch Hugo versions for different projects. Here’s how:

Steps for asdf Users

  1. Install the Hugo Plugin:

    1

    asdf plugin-add hugo

  2. Install a Specific Version:

    1

    asdf install hugo <version>

  3. Switch to the Desired Version:

    1

    asdf global hugo <version>

    This sets the specified version as the global default, making it easy to revert or upgrade as needed.

5. Modify the files(mostly the template file according to ’hugo server‘ command output), and continue to use the current Hugo version

suppose the ‘hugo server’ command output goes like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Start building sites …
hugo v0.136.5+extended darwin/arm64 BuildDate=2024-10-24T12:26:27Z VendorInfo=brew

ERROR deprecated: .Site.IsMultiLingual was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.137.0. Use hugo.IsMultilingual instead.
ERROR deprecated: .Site.RSSLink was deprecated in Hugo v0.114.0 and will be removed in Hugo 0.137.0. Use the Output Format's Permalink method instead, e.g. .OutputFormats.Get "RSS".Permalink
ERROR deprecated: .Site.DisqusShortname was deprecated in Hugo v0.120.0 and will be removed in Hugo 0.137.0. Use .Site.Config.Services.Disqus.Shortname instead.
ERROR deprecated: .Site.Social was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.137.0. Implement taxonomy 'social' or use .Site.Params.Social instead.
ERROR The "tweet" shortcode requires two named parameters: user and id. See "/Users/guanyc/projects/andbible/content/post/hugo-content-management-shortcodes.md:373:1"
ERROR The "tweet" shortcode requires two named parameters: user and id. See "/Users/guanyc/projects/andbible/content/post/hugo-content-management-shortcodes.md:382:1"
ERROR render of "taxonomy" failed: "/Users/guanyc/projects/andbible/themes/even/layouts/_default/baseof.html:54:5": execute of template failed: template: _default/terms.html:54:5: executing "_default/terms.html" at <partial "scripts.html" .>: error calling partial: execute of template failed: html/template:partials/scripts.html:97:14: no such template "_internal/google_analytics_async.html"
ERROR render of "term" failed: "/Users/guanyc/projects/andbible/themes/even/layouts/_default/baseof.html:54:5": execute of template failed: template: _default/taxonomy.html:54:5: executing "_default/taxonomy.html" at <partial "scripts.html" .>: error calling partial: execute of template failed: html/template:partials/scripts.html:97:14: no such template "_internal/google_analytics_async.html"
Built in 116 ms
Error: error building site: render: failed to render pages: render of "404" failed: "/Users/guanyc/projects/andbible/themes/even/layouts/_default/baseof.html:54:5": execute of template failed: template: 404.html:54:5: executing "404.html" at <partial "scripts.html" .>: error calling partial: execute of template failed: html/template:partials/scripts.html:97:14: no such template "_internal/google_analytics_async.html"

we could find and replace the mentioned code with their correpondent suggestions in the files, thanks to Hugo teams for this! foe example: replace .Site.IsMultiLingual with ‘hugo.IsMultilingual’ replace .Site.Social. with .Site.Params.Social

after these replacements, try ‘hugo server’ and check the result.

It may be tedious, but it counts and saves some time! You are using the current version!

remember to backup your files before these modification!

Final Tips

When switching between Hugo versions:

  • Back Up Your Project: Always make a backup or create a Git branch before switching versions in case any changes affect your project.
  • Check for Deprecated Features: Hugo’s changelogs often mention deprecated features or syntax changes that might cause build errors.
  • Test on Local Server: Use hugo server to preview your site locally and catch any issues early.

Switching Hugo versions might seem daunting, but with these methods, you can downgrade, upgrade, or test a specific version without getting tangled up in dependency issues.

References

[]