The Cache-Control
general-header field is used to specify directives for caching mechanisms in both, requests and responses. Caching directives are unidirectional, meaning that a given directive in a request is not implying that the same directive is to be given in the response.
Header type | General header |
---|---|
Forbidden header name | no |
CORS-safelisted response-header | yes |
Syntax
The directives are case-insensitive and have an optional argument, that can use both token and quoted-string syntax. Multiple directives are comma-separated.
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. Be sure to check the compatibility table for their support.
Cache-Control: immutable Cache-Control: stale-while-revalidate=<seconds> Cache-Control: stale-if-error=<seconds>
Directives
Cacheability
public
- Indicates that the response may be cached by any cache.
private
- Indicates that the response is intended for a single user and must not be stored by a shared cache. A private cache may store the response.
no-cache
- Forces caches to submit the request to the origin server for validation before releasing a cached copy.
only-if-cached
- Indicates to not retrieve new data. The client only wishes to obtain a cached response, and should not contact the origin-server to see if a newer copy exists.
Expiration
max-age=<seconds>
- Specifies the maximum amount of time a resource will be considered fresh. Contrary to
Expires
, this directive is relative to the time of the request. s-maxage=<seconds>
- Overrides
max-age
or theExpires
header, but it only applies to shared caches (e.g., proxies) and is ignored by a private cache. max-stale[=<seconds>]
- Indicates that the client is willing to accept a response that has exceeded its expiration time. Optionally, you can assign a value in seconds, indicating the time the response must not be expired by.
min-fresh=<seconds>
- Indicates that the client wants a response that will still be fresh for at least the specified number of seconds.
stale-while-revalidate=<seconds>
- ...
stale-if-error=<seconds>
- ...
Revalidation and reloading
must-revalidate
- The cache must verify the status of the stale resources before using it and expired ones should not be used.
proxy-revalidate
- Same as
must-revalidate
, but it only applies to shared caches (e.g., proxies) and is ignored by a private cache. 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
orIf-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 onhttps://
transactions. For more information, see also this blog post.
Other
no-store
- The cache should not store anything about the client request or server response.
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 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.
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-cache, no-store, must-revalidate
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
Specifications
Specification | Title |
---|---|
RFC 7234 | Hypertext Transfer Protocol (HTTP/1.1): Caching |
RFC 5861 | HTTP Cache-Control Extensions for Stale Content |
draft-mcmanus-immutable-00 | HTTP Immutable Responses |
Browser compatibility
The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Feature | Chrome | Firefox | Edge | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic Support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
immutable | (No) | 49.0 | 15 | (No) | (No) | (No)1 |
stale-while-revalidate | (No)2 | (No)3 | (No) | (No) | (No) | (No) |
stale-if-error | (No)2 | (No)3 | (No) | (No) | (No) | (No) |
Feature | Android | Chrome for Android | Edge mobile | Firefox for Android | IE mobile | Opera Android | iOS Safari |
---|---|---|---|---|---|---|---|
Basic Support | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) | (Yes) |
immutable | (No) | (No) | (No) | (No) | (No) | (No) | (No) |
stale-while-revalidate | (No) | (No) | (No) | (No) | (No) | (No) | (No) |
stale-if-error | (No) | (No) | (No) | (No) | (No) | (No) | (No) |
1. See WebKit bug 167497.
2. See Chromium bug 348877.
3. See Bugzilla bug 995651.