What is Hugo’s build cache and how does it work?

Hugo’s build cache stores rendered content and processed assets to speed up subsequent builds. It’s located in the resources/_gen directory and caches processed images, CSS, JavaScript, and rendered templates. Hugo automatically uses this cache to avoid reprocessing unchanged content, significantly reducing build times for large sites.

How do I enable incremental builds in Hugo?

Use the --ignoreCache flag to disable cache or hugo server with --disableFastRender to force full rebuilds. For incremental builds, simply run hugo without flags—Hugo automatically uses cached content when source files haven’t changed. The HUGO_CACHEDIR environment variable can specify a custom cache location.

What HTTP headers should I set for Hugo static assets?

Set aggressive caching for static assets (CSS, JS, images)- Cache-Control- public, max-age=31536000, immutable (1 year). For HTML pages, use shorter cache times- Cache-Control- public, max-age=3600 (1 hour) with ETag or Last-Modified headers. This allows browsers to cache assets long-term while keeping HTML fresh.

How do I configure CDN caching for a Hugo site?

Configure your CDN (CloudFront, Cloudflare, etc.) to cache static assets with long TTLs (1 year) and HTML with shorter TTLs (1 hour). Set up cache invalidation on deployments. For CloudFront, use the cloudFrontDistributionID in Hugo’s deployment config. Enable compression (gzip/brotli) and set appropriate cache behaviors based on file extensions.

Should I use service workers for Hugo sites?

Service workers can provide offline functionality and improve perceived performance, but they’re optional for static sites. They’re most beneficial for sites that need offline access or want to implement advanced caching strategies. For most Hugo sites, CDN caching and proper HTTP headers are sufficient. Consider service workers if you need offline-first functionality or want to pre-cache critical assets.

How do I configure Hugo’s file caches?

Configure file caches in your config.toml using the [caches] section. Hugo supports multiple cache types- assets , images , getjson , getcsv , getresource , misc , and modules . Each cache type has dir (directory path) and maxAge (expiration time) options. Use tokens like :cacheDir , :resourceDir , and :project for dynamic paths. Set maxAge to -1 for permanent caching, 0 to disable, or a positive number for time-based expiration. See the Hugo cache configuration documentation for details.

Hugo Caching Strategies for Performance

Optimize developing and running Hugo sites

Page content

Hugo caching strategies are essential for maximizing the performance of your static site generator. While Hugo generates static files that are inherently fast, implementing proper caching at multiple layers can dramatically improve build times, reduce server load, and enhance user experience.

Whether you’re using a popular theme from our Most popular themes for Hugo guide or a custom theme, these caching strategies will help optimize your site’s performance.

This comprehensive guide covers build-time caching, incremental builds, CDN optimization, HTTP headers, and asset caching strategies to help you achieve optimal performance for your Hugo-based website.

chef-in-a-white with Caching Strategies This nice image is generated by AI model Flux 1 dev.

Understanding Hugo’s Build Cache

Hugo maintains an internal build cache that stores processed content and assets to speed up subsequent builds. This cache is located in the resources/_gen directory and includes:

Rendered templates: Pre-processed template output
Processed images: Resized, optimized, and converted images
Compiled assets: Minified CSS and JavaScript
Resource metadata: File hashes and processing results

How Build Cache Works

When you run hugo, the generator:

Checks the cache for existing processed resources
Compares file modification times and content hashes
Skips processing unchanged files
Only rebuilds modified or new content

This means that for a site with 1000 posts, editing a single post only requires Hugo to process that one post and regenerate affected pages, not the entire site.

Managing the Build Cache

You can control Hugo’s cache behavior using various command-line flags. For a comprehensive reference of Hugo commands, see the Hugo Cheat Sheet:

# Clear the cache and rebuild everything
hugo --ignoreCache

# Use a custom cache directory
export HUGO_CACHEDIR=/path/to/cache
hugo

# Disable fast render mode (forces full rebuild)
hugo server --disableFastRender

For CI/CD pipelines, consider persisting the cache directory between builds to speed up deployments. If you’re using Gitea Actions for deployment, see our guide on Using Gitea Actions deploy Hugo website to AWS S3 for a complete CI/CD setup:

# Example GitHub Actions workflow
- name: Cache Hugo resources
  uses: actions/cache@v3
  with:
    path: resources/_gen
    key: ${{ runner.os }}-hugo-${{ hashFiles('**/content/**') }}

Configuring File Caches

Hugo provides granular control over different cache types through the [caches] configuration section. According to the Hugo documentation, you can configure multiple cache types:

[caches]
  [caches.assets]
    dir = ':resourceDir/_gen'
    maxAge = -1
  [caches.getcsv]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.getjson]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.getresource]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.images]
    dir = ':resourceDir/_gen'
    maxAge = -1
  [caches.misc]
    dir = ':cacheDir/:project'
    maxAge = -1
  [caches.modules]
    dir = ':cacheDir/modules'
    maxAge = -1

Cache Types Explained

assets: Caches processed CSS, JavaScript, and other assets from Hugo Pipes
getcsv: Caches parsed CSV files loaded via getCSV function
getjson: Caches parsed JSON files loaded via getJSON function
getresource: Caches remote resources fetched via getResource function
images: Caches processed images (resized, optimized, converted)
misc: General-purpose cache for miscellaneous operations
modules: Caches Hugo modules and their dependencies

Configuration Options

Each cache type supports two configuration options:

dir: The absolute file system path where cached files are stored. You can use tokens:
- :cacheDir - Replaced with the configured cache directory
- :resourceDir - Replaced with the resource directory (typically resources/_gen)
- :project - Replaced with the base directory name of the current Hugo project
maxAge: The duration a cached entry remains valid before being evicted:
- 0 - Disables the cache
- -1 - Cache entry never expires (default)
- Positive number - Cache expires after specified duration (e.g., 3600 for 1 hour)

Custom Cache Configuration Example

You can customize cache settings for specific use cases:

[caches]
  # Keep processed images cached indefinitely
  [caches.images]
    dir = ':resourceDir/_gen/images'
    maxAge = -1
  
  # Cache JSON API responses for 1 hour
  [caches.getjson]
    dir = ':cacheDir/:project/json'
    maxAge = 3600
  
  # Cache remote resources for 24 hours
  [caches.getresource]
    dir = ':cacheDir/:project/resources'
    maxAge = 86400

This configuration allows you to:

Keep processed images cached permanently (since they’re deterministic)
Refresh JSON data every hour (for dynamic content)
Cache remote resources for 24 hours (balance between freshness and performance)

The :project token ensures each Hugo project has isolated caches, so running hugo --gc (garbage collection) only affects the current project’s cache.

Incremental Builds

Hugo’s incremental build system is one of its most powerful features. It tracks changes at the file level and only rebuilds what’s necessary.

Enabling Incremental Builds

Incremental builds are enabled by default. Hugo automatically:

Tracks file dependencies
Rebuilds only changed pages and their dependencies
Maintains dependency graphs for efficient updates

Build Performance Tips

Use hugo server for development: The development server uses incremental builds automatically
Leverage --minify only in production: Minification adds overhead; use it only for final builds
Optimize image processing: Use Hugo’s image processing features efficiently:

[imaging]
  bgColor = '#ffffff'
  hint = 'photo'
  quality = 75
  resampleFilter = 'box'

Limit resource processing: Only process images and assets that are actually used

CDN Caching Strategies

Content Delivery Networks (CDNs) are crucial for global performance. When deploying Hugo sites to CDNs like CloudFront, Cloudflare, or Netlify, configure caching appropriately. For detailed instructions on deploying your Hugo site to AWS S3 with CloudFront, see our guide on Deploy Hugo-generated website to AWS S3.

CloudFront Configuration

For AWS CloudFront deployments, configure cache behaviors:

# config.toml
[[deployment.targets]]
name = "production"
URL = "s3://your-bucket?region=us-east-1"
cloudFrontDistributionID = "E1XIDGUJGD9BU9"

Create CloudFront cache behaviors:

Static assets (.css, .js, .jpg, .png, etc.):
- TTL: 1 year (31536000 seconds)
- Cache Policy: CachingOptimized
- Compress: Yes
HTML pages (.html):
- TTL: 1 hour (3600 seconds)
- Cache Policy: CachingDisabled (with origin headers)
- Compress: Yes

Cache Invalidation

Automate cache invalidation on deployments:

# Invalidate CloudFront cache after deployment
aws cloudfront create-invalidation \
  --distribution-id E1XIDGUJGD9BU9 \
  --paths "/*"

Or use Hugo’s deployment feature:

[[deployment.targets]]
name = "production"
URL = "s3://your-bucket"
cloudFrontDistributionID = "E1XIDGUJGD9BU9"

Hugo will automatically invalidate the cache when deploying.

Asset Optimization and Caching

Hugo provides built-in asset processing that integrates with caching.

Resource Hashing

Hugo can automatically add content hashes to filenames:

{{ $css := resources.Get "css/main.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $css.RelPermalink }}">

This generates filenames like main.min.abc123def456.css, enabling long-term caching since the hash changes when content changes.

Image Processing and Caching

Process images efficiently using Hugo’s built-in image processing. Hugo caches processed images, so resizing the same image multiple times only processes it once. For more advanced image handling, including OpenGraph image metadata generation, see our guide on Opengraph image metadata in Hugo static site generator:

{{ $image := resources.Get "images/photo.jpg" }}
{{ $resized := $image.Resize "800x600" }}
<img src="{{ $resized.RelPermalink }}" alt="Photo">

Asset Bundling

Bundle and minify assets:

{{ $css := slice 
    (resources.Get "css/reset.css")
    (resources.Get "css/main.css")
    (resources.Get "css/components.css")
  | resources.Concat "css/bundle.css"
  | minify
  | fingerprint
}}
<link rel="stylesheet" href="{{ $css.RelPermalink }}">

This creates a single cached, minified, and fingerprinted CSS file.

Service Worker Caching (Optional)

For advanced caching strategies, consider implementing service workers:

Basic Service Worker

// sw.js
const CACHE_NAME = 'hugo-site-v1';
const urlsToCache = [
  '/',
  '/css/main.css',
  '/js/main.js',
  '/images/logo.png'
];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then((cache) => cache.addAll(urlsToCache))
  );
});

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request)
      .then((response) => response || fetch(event.request))
  );
});

Register Service Worker

<!-- In your Hugo template -->
<script>
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}
</script>

Monitoring and Optimization

Build Time Monitoring

Track build performance:

# Time your builds
time hugo

# Use verbose output to see what's being processed
hugo --verbose

Cache Hit Rates

Monitor CDN cache hit rates through your CDN’s analytics dashboard. Aim for:

Static assets: >95% cache hit rate
HTML pages: 60-80% cache hit rate (depending on update frequency)

Performance Testing

Use tools like:

Lighthouse: Test caching effectiveness
WebPageTest: Analyze cache headers
GTmetrix: Monitor performance metrics

Best Practices Summary

Enable Hugo’s build cache: Let Hugo cache processed resources
Use incremental builds: Only rebuild what’s changed
Configure CDN properly: Long TTLs for assets, shorter for HTML
Set appropriate HTTP headers: Use immutable for hashed assets
Fingerprint assets: Add content hashes to filenames
Invalidate cache on deployments: Ensure users see updates
Monitor performance: Track build times and cache hit rates
Optimize images: Use Hugo’s image processing efficiently
Bundle assets: Reduce HTTP requests with bundled CSS/JS
Consider service workers: For offline-first or advanced caching needs

Conclusion

Effective caching strategies for Hugo sites involve multiple layers: build-time caching for faster development, CDN caching for global performance, and proper HTTP headers for browser caching. By implementing these strategies, you can achieve:

Faster builds: Incremental builds and build cache reduce build times
Better performance: CDN and browser caching improve load times
Reduced server load: Static assets cached at the edge
Improved user experience: Faster page loads and offline capabilities

Remember that caching is a balance between performance and freshness. Static assets can be cached aggressively, while HTML should have shorter cache times to ensure content updates are visible quickly.