Reducing Hugo Memory Usage on CI Runners

Hugo's speed comes partly from keeping the whole site in memory: every page, its front matter, its rendered content and its output are held until the build finishes. On a laptop with 32 GB nobody notices. On a hosted CI runner or a static host's build container with 4 GB, a growing docs site one day fails with fatal error: runtime: out of memory or is killed silently by the container, and the build that took 40 seconds yesterday does not complete today.

This guide measures peak memory on a 30,000-page Hugo site, identifies what drives it, and applies the changes that cut it from 7.8 GB to 3.1 GB so the build fits comfortably in a standard runner again. It is part of Hugo Build Times for Large Repositories.

Prerequisites

• Hugo extended 0.120 or newer.
• A CI job where you can wrap the build command and read its output.
• The ability to run the build locally with the same content, to iterate faster than CI allows.

Step 1: Measure Peak Memory

Wall time is logged by every CI system; peak memory is not. Add it:

/usr/bin/time -v hugo --gc --minify 2> time.txt
grep -E 'Maximum resident set size|Elapsed' time.txt
#   Maximum resident set size (kbytes): 8164320
#   Elapsed (wall clock) time (h:mm:ss or m:ss): 1:47.21

For a timeline rather than a single number, hugo --printMemoryUsage logs heap usage every few seconds, which shows whether the peak happens during content loading, rendering or image processing. On this site the peak came late in rendering, when image processing and page output overlapped.

Reading the shape is worth a minute before changing anything. A curve that climbs steadily and stays high points at content and data held for the whole build. A late spike that collapses points at a phase — image processing, a large output format, a template that assembles a huge slice on some pages. A sawtooth suggests garbage collection is keeping up and the peak is set by a single moment of overlap, which is often fixable by reducing concurrency during that phase.

Step 2: Find What Drives the Peak

Build variations of the site with one factor removed at a time and measure each:

Step 3: Apply the Fixes

Cap Hugo's caches. HUGO_MEMORYLIMIT tells Hugo how much memory (in GB) to aim for with its internal caches; it evicts more aggressively as it approaches the limit. On a 4 GB runner, HUGO_MEMORYLIMIT=2 reduced the peak by 1.1 GB at a cost of 6 seconds of build time.

Process images once, outside the render. Most image memory came from resizing thousands of images during rendering while pages were also held in memory. Two changes helped. First, persist Hugo's resources/_gen directory between CI runs (see Caching Hugo Builds in GitHub Actions) so unchanged images are not reprocessed at all. Second, standardise on three widths instead of per-template ad hoc sizes; the site had 11 distinct sizes, most used on one template. With a warm resource cache and fewer variants, image memory fell from 2.9 GB to 0.4 GB.

Stop loading giant data files into every build. The 410 MB API reference JSON in data/ was parsed at startup and held for the whole build, although only 2,000 reference pages used it. Converting it to a content adapter (_content.gotmpl, available since Hugo 0.126) that creates pages from the data, or splitting it into one file per API group read with resources.Get only by the pages that need it, cut 0.9 GB.

Drop unused page kinds. The site generated taxonomy and term pages for tags nobody browsed. disableKinds = ['taxonomy', 'term'] for tags (keeping categories) removed 9,400 pages and 1.2 GB. Check analytics before removing anything readers use.

Review large output formats. The search JSON output format built a single file of every page's full content. Replacing it with Pagefind, which indexes the built HTML after Hugo exits, moved that memory out of the Hugo process entirely — see Indexing Hugo Sites with Pagefind.

# hugo.toml (excerpt)
disableKinds = ['taxonomy', 'term']
[imaging]
  quality = 78
  resampleFilter = 'Lanczos'
[caches.images]
  dir = ':resourceDir/_gen'
  maxAge = -1

# CI step
- run: /usr/bin/time -v hugo --gc --minify 2> time.txt
  env: { HUGO_MEMORYLIMIT: '2' }

Measured Impact

The cold-cache build is slower than before because processed images are written to a cache directory that is then persisted; the first build pays for it once. Every subsequent build with the cache restored was 43 seconds faster than the original.

Template Patterns That Inflate Memory

Some memory comes from templates rather than content. Three patterns showed up on this site. A related-pages partial called site.RegularPages.Related with a broad index on every page, building a large intermediate slice 30,000 times; restricting the indices to tags and section and capping results at five cut its allocation sharply. A "recent updates" footer sorted all regular pages by date on every page; moving it into a partialCached call made it run once. And a shortcode that read an entire JSON file with transform.Unmarshal on each use loaded the same 40 MB file hundreds of times; reading it once through resources.Get, which Hugo caches, fixed it. --templateMetrics shows these as templates with high cumulative time, and they are usually the same templates that dominate memory.

Watching the Trend

Memory grows with content, so a fix today is not permanent. Record peak RSS on every main-branch build next to build time, and alert when it crosses 70% of the smallest environment the site must build in — the hosted build container, not the CI runner. On this site the growth rate after the fixes was about 90 MB per 1,000 pages, which gives roughly 9,000 pages of headroom before the next intervention; that number is now in the quarterly planning notes rather than discovered by a failed deploy. The same monitoring pattern is described in Measuring Build Time Regressions in CI.

Pitfalls & Rollback

• Measuring only wall time. Memory problems appear as sudden failures, not gradual slowdowns. Record peak RSS.
• Upgrading the runner and stopping there. The problem returns as content grows; reduce usage too.
• Disabling page kinds readers use. Check analytics before removing taxonomies or outputs.
• Forgetting the hosted build. A site that builds in CI but deploys via the host's own builder must fit the host's limits.
• Rollback: each change is a config line, a CI environment variable or a template change; revert individually and re-measure.

Conclusion

Hugo's memory usage grows with the site, and the first sign is usually a build that fails outright. Measuring peak RSS, attributing it by removing one factor at a time, and then capping caches, persisting and standardising image processing, moving giant data files out of data/, and dropping unused page kinds took a 30,000-page site from 7.8 GB to 3.1 GB and made warm builds 40% faster in the process.

FAQ

Why does Hugo use so much memory on large sites?

Hugo holds the whole site in memory while building — every page's content, rendered output and metadata — so memory grows with page count and content size. Image processing, large data files and templates that build big slices on every page add to the peak.

How do I see Hugo's peak memory usage?

Wrap the build with /usr/bin/time -v and read the maximum resident set size, or run hugo with --printMemoryUsage to log memory periodically. Record it in CI alongside build time so growth is visible.

Does HUGO_MEMORYLIMIT help?

It sets the memory Hugo aims to stay within for its caches, in gigabytes, and Hugo evicts cached items more aggressively as it approaches the limit. It lowers peak usage at some cost in build time, and is the first setting to try on constrained runners.

Should I just use a bigger runner?

It is a valid short-term fix, but memory grows with content, so the problem returns. Reducing peak usage first keeps builds on standard runners and makes the growth rate visible.

Related

• Parent: Hugo Build Times for Large Repositories — build performance on large Hugo sites.
• Hugo partialCached for Faster Builds — the time side of template work.
• Caching Hugo Builds in GitHub Actions — persisting the resource cache.
• Optimizing WebP Images in Hugo Without Plugins — standardising image variants.
• Search Index Size Budgets for Large Docs — moving search indexing out of the build.