Cache-Control

The Cache-Control HTTP header holds directives (instructions) for caching in both requests and responses. A given directive in a request does not mean the same directive should be in the response.

Header type General header
Forbidden header name no
CORS-safelisted response header yes

Syntax

Caching directives have the following rules to be valid:

  • Case-insensitive, but lowercase is recommended.
  • Multiple directives are comma-separated.
  • Some directives have an optional argument, which can be either a token or a quoted-string. (See spec for definitions)

Cache request directives

Standard Cache-Control directives that can be used by the client in an HTTP request.

Cache-Control: max-age=<seconds>
Cache-Control: max-stale[=<seconds>]
Cache-Control: min-fresh=<seconds>
Cache-Control: no-cache 
Cache-Control: no-store
Cache-Control: no-transform
Cache-Control: only-if-cached

Cache response directives

Standard Cache-Control directives that can be used by the server in an HTTP response.

Cache-Control: must-revalidate
Cache-Control: no-cache
Cache-Control: no-store
Cache-Control: no-transform
Cache-Control: public
Cache-Control: private
Cache-Control: proxy-revalidate
Cache-Control: max-age=<seconds>
Cache-Control: s-maxage=<seconds>

Extension Cache-Control directives

Extension Cache-Control directives are not part of the core HTTP caching standards document. Check the compatibility table for their support; user-agents that don't recognize them should ignore them.

Cache-Control: immutable 
Cache-Control: stale-while-revalidate=<seconds>
Cache-Control: stale-if-error=<seconds>

Directives

Cacheability

public
The response may be cached by any cache, even if the response is normally non-cacheable. Examples of normally non-cacheable responses:
  • The response does not contain a max-age directive or Expires header
  • The response is to a POST request
private
The response is for a single user and must not be stored by a shared cache. A private cache (like the user's browser cache) may store the response.
no-cache
Caches must check with the origin server for validation before using the cached copy.
no-store
The cache should not store anything about the client request or server response.

Expiration

max-age=<seconds>
The maximum amount of time a resource is considered fresh. Unlike Expires, this directive is relative to the time of the request.
s-maxage=<seconds>
Overrides max-age or the Expires header, but only for shared caches (e.g., proxies). Ignored by private caches.
max-stale[=<seconds>]
Indicates the client will accept a stale response. An optional value in seconds indicates the upper limit of staleness the client will accept.
min-fresh=<seconds>
Indicates the client wants a response that will still be fresh for at least the specified number of seconds.
stale-while-revalidate=<seconds> 
Indicates the client will accept a stale response, while asynchronously checking in the background for a fresh one. The seconds value indicates how long the client will accept a stale response. See "Keeping things fresh with stale-while-revalidate" for more information.
stale-if-error=<seconds> 
Indicates the client will accept a stale response if the check for a fresh one fails. The seconds value indicates how long the client will accept the stale response after the initial expiration.

Revalidation and reloading

must-revalidate
Indicates that once a resource becomes stale, caches must not use their stale copy without successful validation on the origin server.
proxy-revalidate
Like must-revalidate, but only for shared caches (e.g., proxies). Ignored by private caches.
immutable
Indicates that the response body will not change over time. The resource, if unexpired, is unchanged on the server and therefore the client should not send a conditional revalidation for it (e.g. If-None-Match or If-Modified-Since) to check for updates, even when the user explicitly refreshes the page. Clients that aren't aware of this extension must ignore them as per the HTTP specification. In Firefox, immutable is only honored on https:// transactions. For more information, see also this blog post.

Other

no-transform
No transformations or conversions should be made to the resource. The Content-Encoding, Content-Range, Content-Type headers must not be modified by a proxy. A non-transparent proxy or browser feature such as Google's Light Mode might, for example, convert between image formats in order to save cache space or to reduce the amount of traffic on a slow link. The no-transform directive disallows this.
only-if-cached
Indicates to not retrieve new data. This being the case, the server wishes the client to obtain a response only once and then cache. From this moment the client should keep releasing a cached copy and avoid contacting the origin-server to see if a newer copy exists.

Examples

Preventing caching

To turn off caching, you can send the following response header. In addition, see also the Expires and Pragma headers.

Cache-Control: no-store

Caching static assets

For the files in the application that will not change, you can usually add aggressive caching by sending the response header below. This includes static files that are served by the application such as images, CSS files and JavaScript files, for example. In addition, see also the Expires header.

Cache-Control: public, max-age=31536000

Requiring revalidation

Specifying no-cache or max-age=0 indicates that clients can cache a resource and must revalidate each time before using it. This means HTTP request occurs each time, but it can skip downloading HTTP body if the content is valid.

Cache-Control: no-cache
Cache-Control: max-age=0

Specifications

Specification Status Comment
RFC 8246: HTTP Immutable Responses IETF RFC
RFC 7234: Hypertext Transfer Protocol (HTTP/1.1): Caching IETF RFC
RFC 5861: HTTP Cache-Control Extensions for Stale Content IETF RFC Initial definition

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Cache-ControlChrome Full support YesEdge Full support 12Firefox Full support YesIE Full support YesOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
immutable
Experimental
Chrome No support No
Notes
No support No
Notes
Notes See Chromium bug 611416.
Edge Full support 15Firefox Full support 49IE No support NoOpera No support NoSafari Full support 11WebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS Full support 11Samsung Internet Android No support No
stale-if-error
ExperimentalNon-standard
Chrome No support No
Notes
No support No
Notes
Notes See Chromium bug 348877.
Edge No support NoFirefox No support No
Notes
No support No
Notes
Notes See Bugzilla bug 995651 comment 7.
IE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
stale-while-revalidate
ExperimentalNon-standard
Chrome Full support 75Edge No support NoFirefox Full support 68IE No support NoOpera No support NoSafari No support NoWebView Android Full support 75Chrome Android Full support 75Firefox Android Full support 68Opera Android No support NoSafari iOS No support NoSamsung Internet Android No support No

Legend

Full support  
Full support
No support  
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
See implementation notes.
See implementation notes.

See also