Right, let’s talk about the file cache. This isn’t some magical, abstract layer; it’s literally a directory on your disk where Hugo stashes stuff it thinks it might need again. Its entire reason for being is to stop Hugo from doing the same expensive work over and over. Think of it less like a “cache” and more like Hugo’s workshop whiteboard—it’s covered in half-scribbled calculations so it doesn’t have to re-derive the Pythagorean theorem every time it needs to build a page.

By default, this glorious mess of files lives in resources/_gen (for processed images, SCSS, etc.) and hugo_cache (for parsed modules and other goodies) within your project root. The first thing you should do is add these to your .gitignore file immediately. Committing these is like vacuuming up sawdust, balling it in a box, and mailing it to a friend. It’s useless to anyone but the machine that created it, and it will cause nothing but merge conflicts.

# .gitignore
/resources/_gen/
/resources/_gen_remote/
/hugo_cache/

The resources/_gen/ Directory: Where the Magic (and Bloat) Happens

This is Hugo’s asset pipeline workshop. When you throw an image at it with .Resize, or a Sass file, Hugo doesn’t just do the transformation and serve the result. It calculates a fingerprint (usually a hash) of the source file and the processing instructions. It then saves the final product in resources/_gen/assets/ using a name that incorporates that fingerprint.

Why the fingerprint? It’s brilliant, really. It means every processed asset is perfectly immutable and cacheable forever. If you change the source image or your SCSS, the fingerprint changes, and Hugo generates a new file with a new name. The old one just sits there, useless, until you run hugo --cleanDestinationDir which, bless its heart, will politely clean it up for you. This is why you can get away with aggressive caching on your CDN for your /assets/ directory—the filename itself is a guarantee the content will never change.

The hugo_cache/ Directory: The Brain’s Scratchpad

While resources/_gen is for final products, hugo_cache/ is for Hugo’s internal homework. This is where it caches the parsed output of your modules (like your theme), the results of expensive data processing (like a giant JSON file fetched from an API), and other pre-build computations.

The most important thing to know about this directory is that its contents are not inherently portable. If you’re working on a team or using a CI/CD pipeline, you might be tempted to cache this directory to speed up builds. Tread carefully. The cache entries can contain absolute filesystem paths. If your CI machine has a different directory structure than your laptop, Hugo will look at the cached path, say “that’s not where that file is on this machine,” and ignore the cache. You’ll have a nice, warm cache directory that does absolutely nothing. The best practice is to let each build environment manage its own hugo_cache locally.

Taking Control: Configuring the Cache Dir

You’re not stuck with the default location. If you want to shift this off your precious SSD or onto a ramdisk for ludicrous speed, you can configure the path in your hugo.toml:

[caches]
#[caches.getjson]
#dir = ':cacheDir/:project'
[caches.assets]
dir = ':cacheDir/:project/assets'
[caches.images]
dir = ':cacheDir/:project/images'
[caches.modules]
dir = ':cacheDir/:project/modules'

# This is the base dir for the above, the important one!
[caches]
cacheDir = '/my/super/fast/volume/hugo_cache_projects'

The variables :cacheDir and :project are your friends here. :project is the base project directory name, which helps avoid collisions if you have multiple sites. Placing this on a ramdisk (like /tmp/my_hugo_cache) is a fantastic trick for squeezing every last drop of performance out of a large site on your local machine.

When to Nuke it From Orbit

The cache is smart, but it’s not infallible. If you ever see Hugo behaving strangely—a change not reflecting, an old image stubbornly hanging around, or just general spooky action at a distance—your first troubleshooting step should be to blow away the cache directories. Stop the server, delete resources/_gen and hugo_cache, and restart. This forces a complete rebuild from scratch. It’s the equivalent of turning it off and on again, and I’m not ashamed to say it solves the problem 99% of the time. It’s not a sign of weakness; it’s a pragmatic use of a disposable resource. Now you know what it is, you can delete it with confidence.