Cache busting

Definition and scope

In web performance, cache busting refers to any strategy that turns a new asset version into a new cache key, so that caches cannot mistake it for the previous file. It most commonly applies to static assets—images, CSS, JavaScript, fonts—but the principle is the same for any cacheable resource. By versioning the URL itself, teams can set aggressive Cache-Control policies (for example, a year) without risking that clients retain outdated assets after a change. The scope spans browser caches, intermediary proxies, enterprise gateways, and CDNs.

Practically, cache busting is orthogonal to server-side purging and client revalidation. Purging removes an object from a specific cache; revalidation asks whether a cached object is still fresh. Busting sidesteps both concerns by publishing a new URL that all layers treat as a different object. For image optimisation workflows, this provides predictable rollouts, reduces support overhead from stale assets, and simplifies CDN configuration because correct behaviour does not depend on validators or conditional requests being honoured by every intermediary.

Overview

Two broad approaches exist: filename hashing and query-string versioning. Filename hashing embeds a content hash into the file path (for example, /img/hero.9f3a2.webp). Query-string versioning appends a token (for example, /img/hero.webp?v=9f3a2). Both alter the cache key; the choice can depend on CDN behaviour, legacy proxies, and tooling. Hashes are typically derived from the file’s bytes, guaranteeing that any bit-level change yields a different value, though teams sometimes use build numbers or timestamps for simplicity at the cost of precision.

Cache busting pairs with long-lived caching headers such as Cache-Control: public, max-age=31536000, immutable. The immutable directive signals that the resource will never change at that URL, encouraging browsers to avoid revalidation. This is attractive for heavy image assets because it maximises repeat-view performance and offloads traffic from origin. When combined with responsive image markup (srcset and sizes) or CDNs that perform on-the-fly transformation, cache busting should be applied to the canonical upstream asset and to each derivative where the URL is stable across users.

What cache busting changes: Adding a version to an image URL (e.g., /img/hero.9f3a2.webp or /img/hero.webp?v=9f3a2) creates a new cache key for browsers, CDNs, and intermediary proxies. All layers treat the new URL as a distinct resource.

HTTP caching is keyed primarily by the request URL plus select headers (depending on the cache). When a version is embedded in the image URL, every cache along the path stores it under a new key. The browser will download the updated file once and then reuse it until the next versioned URL appears. CDNs similarly see and store each version separately, which avoids serving stale content during rollout and enables blue–green style deployments where both old and new versions can coexist without conflict.

Because the URL changes, validators like ETag or Last-Modified play a smaller role for versioned assets; the cache lifetime can be long and immutable. Revalidation still matters for unversioned endpoints and for caches that normalise keys. Some CDNs and proxies may ignore certain query parameters or only include whitelisted parameters in the cache key. Where that is a risk, filename hashing is more robust. If query parameters are used, the CDN should be configured to include the version parameter in cache key calculation to guarantee correct behaviour at edge and origin tiers.

Build tools and bundlers

Modern build systems automate cache busting by generating content-hashed filenames and rewriting references throughout the bundle. Webpack, Vite, Parcel, and Rollup can emit assets as [name].[contenthash].[ext] and update HTML templates, CSS url() references, and JavaScript imports. For images, these pipelines can also in-line small files as data URLs, emit separate files for larger assets, and expose URLs at build time, ensuring that <img>, <source>, and srcset attributes point to the correct, versioned paths. Static site generators and headless CMS integrations often provide similar manifest-based rewriting.

For teams using query-string versioning, build steps typically inject a release identifier (for example, a Git commit or build number) as ?v=XYZ across asset URLs. This approach is simpler to implement in templating systems and server-side frameworks that do not manage file output names. However, content hashing is generally safer because it avoids unnecessary busts when unrelated assets change and guarantees a new URL only when the file bytes differ. Whichever approach is chosen, the build should produce a manifest mapping original paths to versioned ones, to support server-side rendering and runtime templates.

Risks and trade-offs

• Cache fragmentation and storage: every new version consumes space in browser caches, CDNs, and origins until eviction or purge, which can increase storage and egress costs.
• Operational hygiene: broken references may occur if HTML or CSS still points to an old hash after deploy. Atomic releases or manifest-driven rewrites reduce this risk.
• Proxy behaviour: some intermediaries drop or ignore query parameters in cache keys by default. Filename hashing is safer when infrastructure cannot be guaranteed or configured end-to-end.
• SEO implications: search engines treat each versioned URL as a separate resource. If images are discoverable in sitemaps or linked publicly, high churn increases crawl overhead and index noise.
• Service worker coordination: custom caches must be invalidated consistently with URL versioning to avoid serving stale assets from the service worker layer when the page references new URLs.

Implementation notes

Set long-lived headers on versioned assets: Cache-Control: public, max-age=31536000, immutable is conventional for hashed images. For unversioned endpoints (for example, dynamic image transformers), pair sensible max-age with revalidation directives (ETag, Last-Modified) and ensure CDNs respect Vary headers that affect image variants, such as Accept or DPR. When using query parameters for versioning, configure the CDN to include that parameter in the cache key and to pass it through to origin where necessary to avoid key normalisation issues.

Prefer content hashes over timestamps or global build numbers for finer granularity. A content hash only changes when the file changes, limiting cache churn and storage growth. Coordinate versioning across responsive markup: ensure all entries in srcset (and any <source> elements in <picture>) reference the correct versioned paths. If a CDN generates responsive variants on the fly, the upstream canonical image can be hashed, while derivative URLs incorporate both the canonical version and their transformation parameters for stable caching at the edge.

Plan for rollbacks and purges. Because all versions coexist until eviction, a rollback simply references the prior URL; no purges are required for safety but may be desirable to reclaim storage. For stricter control, implement automated purges for superseded versions after a cooling-off period. In service workers, version the cache name alongside URLs, remove old caches during activate, and avoid opaque matching logic that might serve an older entry for a new request. Monitor hit ratios and byte hit ratios to balance storage and performance across edge locations.

Comparisons

Filename hashing vs query-string versioning

Filename hashing is the most robust option across browsers, proxies, and CDNs because the entire path changes and will form part of the cache key in virtually all environments. Query parameters are simpler to retrofit but can be dropped or excluded from cache keys by some caches unless explicitly configured. For image-heavy sites with multiple intermediaries or legacy infrastructure, filename hashing is usually preferable. Where tooling or hosting constraints make path changes difficult, query-string versioning can suffice if the CDN’s cache key includes the version parameter end-to-end.

Busting vs purging vs revalidation

Cache busting publishes a different URL and does not depend on caches discarding older entries. Purging targets specific caches to delete an object at its current URL. Revalidation keeps the URL the same and asks the origin whether the cached copy is still valid. In practice, busting plus long max-age is used for static images; purging is reserved for operational clean-up or emergency fixes; revalidation is more appropriate for unversioned or frequently changing endpoints where URLs cannot change.

Immutable caching vs short TTLs without versioning

Short TTLs reduce staleness risk but increase origin traffic and latency, especially for image-heavy pages. Immutable caching with versioned URLs shifts the trade-off: almost zero origin hits for repeat views and predictable updates on deploy. The latter generally yields better performance and lower cost at scale, provided that deployment processes handle reference rewriting reliably and that storage growth from multiple versions is managed with periodic purges.

FAQs

Should image cache busting use hashed filenames or version query parameters?

Hashed filenames are more dependable across CDNs and proxies because they guarantee a new cache key without special configuration. Query parameters are easier to inject in templates but require confirming that the CDN includes the parameter in its cache key and does not strip it at the edge. If infrastructure control is limited or unknown, prefer filename hashing; otherwise, either can work so long as the version is part of the cache key at every layer.

How long should versioned images be cached?

A common pattern is Cache-Control: public, max-age=31536000, immutable for versioned images. This maximises repeat-view performance while ensuring updates take effect by changing the URL. For assets that may be regenerated in place by a transformer, use shorter max-age with strong validators, but maintain versioned URLs for canonical inputs to avoid serving stale data from intermediary caches during high traffic periods.

Does cache busting affect SEO for images in search results or sitemaps?

Search engines treat each versioned URL as a separate file. That is acceptable for embedded page assets, but if image URLs are exposed in sitemaps or intended for image search, frequent version churn can add crawl overhead and dilute signals. Limit busts to meaningful visual changes, keep canonical image URLs stable when possible, and use consistent alt text and structured data so ranking signals are not fragmented across versions.

How does cache busting interact with responsive images and CDNs that transform assets on the fly?

Use versioned canonical source URLs so that any transformation pipeline produces derivative URLs that indirectly encode the version. If the CDN includes transformation parameters in the cache key (for example, width, format), each variant is cached separately. When you publish a new source version, the CDN will generate and cache new derivatives under distinct URLs, while old variants remain accessible until they expire or are purged. Ensure templates update all srcset entries consistently during deploys.