How Often Do You Update Hugo and Why?

I would like to start a discussion here for anyone interested in sharing.

The broad question

How often do you update Hugo and what is the reason and process behind that?

For Website Maintainers

Do you upgrade to the latest version of Hugo for your website as soon as it comes out? If not, what is your process? Do you wait ‘X’ number of days? Do you run one version behind? Something else?

Does the version of Hugo you run locally typically differ from the version you might build your site with on CI? Netlify?

For Theme Creators & Maintainers

How do you decide what is the minimum Hugo supported version? Do you test your theme with the latest Hugo version? Do you test your theme with the last 5 Hugo versions? What is your philosophy behind this?

I have a hunch that many theme creators “set it and forget it” by not really testing their themes with newer Hugo versions after they publish. I hope I’m wrong but I could understand it.

Thank you in advance for answering.

If I have time, I try to keep it updated regularly. I keep old versions, so I can use that if I need it, to make a quick change in an older site, because sometimes using the latest will not work with the templates you wrote with an older version, and, you don’t have time to go through with the latest and make it all work again.

For any new site, I use the latest because it makes no sense to use an older version for that.


As a theme developer, I try to avoid incrementing the Hugo version unless I know that I’ve added something that will require a newer version. For instance, I’m in the process of adding validation/error checking to my theme, which requires at least version 0.30. This is mostly for people using Linux distributions that package Hugo but don’t immeiately update it to the newest version.

1 Like

I have Hugo installed via Mac Homebrew so it (potentially) gets updated every time I do a ‘brew update’ which is pretty much every day. But, as yet, I’m still developing my site locally and don’t have anything online with Hugo. If and when my site ever gets finished I may be a little more careful.

Being relatively incompetent with regard to web development and Go/Hugo in particular I figure I may as well struggle with the latest and greatest version rather than some random previous version … :wink:

1 Like

As I am only building \ maintaining one website, I upgrade straight away. If I have to fix or update the code as a result I will do that.

I don’t want to be in a situation where I want a new feature in the latest version, but then realise that the prior dozen or so versions require code modifications too. It is easier to do it incrementally.

In addition, it is very easy to test locally any updates on a different branch before pushing to prod. In the last 4 months or so, I think I have only ever needed to make one minor modification to the code anyway.


I use Homebrew on a Mac, but I leave hugo pinned at a tested version and manually download new versions to regression-test before upgrading. I build both of my sites with both versions and then run diff -r against the output; if I see anything other than the Hugo version string in the output, I know something has changed. Usually the changes are expected based on the release notes, but I’ve caught a few bugs in the past.

If there’s nothing unexpected in the diff, I unpin, upgrade, and re-pin.

The themes for both sites were written from scratch, so I don’t have any third-party dependencies to worry about. Only one of my themes is public, and it’s mostly just a simple demo of using one level of nested sections, rather than something other people are likely to use, but since I use it, it’s kept up to date.



Note that for the themes site we build a demo for almost all of the themes (we have a couple on a no demo list for different reasons). We could do better on the error reporting here, but currently

  • If a theme fail to build its example site, it gets logged and we remove the “demo button”
  • If many theme fails (I think more than about 10%) , the build fails
1 Like

Thank you everyone for the comments thus far.

How far back? Does that depend on your oldest site? Or do you just keep maybe the last 5 versions or something?

How do you go about testing your theme? The Hugo demo site? A personal site? Multiple?

We all start off as beginners. Thank you for sharing.

Interesting, is this something you do via Homebrew itself (the pinning)?

Haven’t heard of that before. That sounds like it might be useful. I’ll see if I can work something like that out in my workflow.

Some Context

In case anyone was curious where these questions are coming from, here it is.

I build all of my Hugo websites (at least 4 public as of now) with CircleCI. I use the Hugo Docker Image I created specifically to help test the sites. It test to make sure Hugo itself completes successfully, but also HTML quality and broken links.

I’m trying to determine how many versions back of Hugo should be supported in this image. This means 2 different things:

  1. The existence of the Docker tag for a Hugo version itself. Without this, you wouldn’t be able to use this Hugo version at all.
  2. When to “update” the image. Aside from Hugo, underlying tools such as the version of Ruby, HTML Proofer, and Nokogiri can change. Should I update an existing Hugo Docker image that is already made with newer versions of these tools? Or just when a new version of Hugo is released?

Also, I have a single public theme but I hope to create more in the future. I would like to come up with a CI process in order to test Hugo themes with several versions of Hugo. It would be great to have automated testing that says, "Hey, this Hugo theme has been tested with Hugo versions 0.28, 0.29, and 0.30.2 and should work fine.

Similar to how an open-source Python project might test with multiple versions of Python (both major and minor releases).

To that end, I’m trying to to figure out how often and how people update to newer versions of Hugo. Myself, I update my Docker image to support the newest version of Hugo usually within 12 hours. I then have my sites upgrade to that new version the next time I touch that site, whatever reason that may be.

This is something I also do. I actually have my Hugo executable as part of my github repo. Therefore I can go back to any point in time with the correct hugo version.


brew pin hugo
brew unpin hugo
brew list --pinned

I haven’t released a theme and supported it yet, so I might do something different if that happens. For now I use snap, which wonderfully updates itself without me noticing. I update the tag URL in my .gitlab-ci.yml when I make a note about a new version (I write notes for myself about changes).

I should point out that my site and theme is so basic and simple, I doubt there are many breaking changes due to Hugo version. Not sure what I’ll do when it gets complex. :slight_smile:

Haven’t looked but I have a couple sites that have not been updated in 2 years, so, it’s pretty far back.

@Jonathan_Griffin I like your idea of putting the working version in the repo. Thanks for that.

Be careful though because your repo size will grow much faster for committing the hugo binaries (or any binary for that matter).

I made that mistake earlier and I caught that mistake soon as I build the latest Hugo binary couple of times a week. I then filter purged my repo off all commits with Hugo binary and moved the binary to a separate repo. I now just force push commits to the binary-only repo to prevent that repo from hogging unnecessary disk space.

Now I add that binary-only repo as a submodule in my site repo.

I should though atleast start adding the Hugo version number in the site repo commits each time I update that submodule reference.

1 Like

Good point @kaushalmodi.

As an aside, if I ever have to purge a file from a git repo (like oops I committed a giant file or oops I committed a password), I like this util:


I pull the code and rebuild before I start working on a site. I like to run with the current master so that I can test it out.

If a site requires a certain build of Hugo, I’ll leave a copy of the Hugo bin with it (I have a script to build sites and it checks the site root in a case statement that can override the name of the Hugo binary to use).

I still run with the good ole’ Hugo 0.13. But I’m a vintage kind of guy. Just watching season 2 of Stranger Things.


It depends on the change. If it’s a small bugfix, I typically test it with a single site in a browser that is experiencing the issue, then call it good. New features or other big changes get tested on one or more of the websites I maintain that use the theme (a total of four) on at least Firefox and a Chromium browser. Since my theme is heavily customizable and requires a number of extra options to be set, the demo Hugo site doesn’t work, so the “demo” is the theme’s website, though that doesn’t even use all of the features.

It’s all manual testing, visually checking to see that things are working as they should. That does sometimes lead to me committing changes that break something, but I’ll usually notice and push a change soon after than fixes that. When it comes to the error checking, I try a set of potential kinds of bad values and check that they do not validate, as well as any kind of valid value. The largest example of this is testing that a custom color is a valid CSS color, which involves three separate regular expressions and a JSON file.

I might be late to the party, but here it goes.

I use Hugo in my Netlify builds. Netlify allows for custom Hugo versions based on the deploy you use. Here’s small write-up here with some of the setup for a different purpose.

This allows me to branch the master of my repository and target a certain version of Hugo. No need to worry about what version I am at, because no matter what commit is published allows for the correct Hugo version. I can also target my Hugo builds with checking for what deploy I am using, so I can include debug scripts in my Hugo build on non-production builds. This is working awesome!

Probably does not help you much with what you are doing, but in the case someone wants to have more control of their builds to test in the wild, Netlify works pretty well. I can always target any branch I want back to any version without any real consequences to the public/production deploy.

1 Like