Cache-Control header

This feature exist well institute and bring across many device and browser version . It’s been available across browsers since July 2015.

• Learn more
• See full compatibility
• Report feedback

The HTTPCache-Controlheader holddirectives( instruction ) in both petition and responses that control caching in browsers and share caches ( e.g. , Proxies , CDNs ) .

• Caching directives be case-insensitive . Even so , lowercase live recommended because some implementations do not recognize uppercase directives .
• Multiple directives are permitted and must exist comma-separated ( e.g. ,Cache-control : max-age=180 , public) .
• Some directives make an optional debate . When an argument is provided , it equal separated from the directive epithet by an peer symbol (=) . Typically , arguments for the directives cost integers and are therefore not enclose in quote characters ( e.g. ,Cache-control : max-age=12) .

Cache directives

The following table list the standardCache-Controldirectives :

Note : Check the compatibility table for their support ; user agent that do n’t make out them should disregard them .

Vocabulary

This section defines the price used in this papers , some of which are from the specification .

Implementation that holds request and reaction for reusing in subsequent petition . It can be either a shared cache or a private cache .

Cache that exist between the origin server and customer ( e.g. , Proxy , CDN ) . It stores a single response and reuses it with multiple user — so developer should avoid store personalized contents to be cached in the shared cache .

Cache that survive in the client . It be as well namelocal cacheorbrowser cache. It can store and reuse personalized content for a single user .

Store a response in caches when the response is cacheable . Still , the cached response live not ever reused as-is . ( Usually , “ cache ” think of store a reply . )

Ask the origin server whether or not the stored response is still fresh . Usually , the revalidation be done through a conditional request .

Suggest that the answer cost new . This usually means the response can be reused for subsequent requests , depending on petition directives .

Signal that the response be a stale reply . This usually means the response ca n’t be reused as-is . Cache memory be n’t required to remove stale response instantly because revalidation could change the response from being stale to cost new again .

The time since a reply was generate . It is a standard for whether a response is new or stale .

Directives

This segment lists directives that affect caching — both reception directives and petition directives .

Response Directives

max-age

Themax-age=Nresponse directive indicates that the reaction stay fresh untilNseconds after the answer is generate .

Indicates that caches can store this response and reuse it for subsequent petition while it ‘s novel .

Note thatmax-ageis not the elapsed time since the reply was welcome ; it be the elapsed time since the reaction live generated on the origin waiter . So if the early cache ( s ) — on the network route taken by the response — store the response for 100 instant ( indicated using theYearsreply header subject ) , the browser cache would deduct 100 seconds from its novelty lifetime .

If themax-agevalue is negative ( for example ,-1) or is n’t an integer ( for example ,3599.99) , then the caching conduct is unspecified . Caches are advance to treat the value as if it live0( this equal noted in the Calculating Freshness Lifetime division of the HTTP specification ) .

s-maxage

Thes-maxageresponse directive indicates how long the response remains fresh in a shared cache . Thes-maxagedirective equal ignored by private caches , and override the value specify by themax-agedirective or theExpiresheader for shared caches , if they exist present .

no-cache

Theno-cacheresponse directive indicate that the response can equal stored in caches , but the reaction must live validated with the ancestry server before each reuse , still when the cache equal disconnected from the ancestry waiter .

If you require caches to always check for content updates while reusing stored content ,no-cachebe the directive to use . It does this by expect caches to revalidate each request with the origin server .

Bill thatno-cachedoes not intend “ serve n’t cache ” .no-cacheallows caches to store a reception but necessitate them to revalidate it before reuse . If the sense of “ serve n’t cache ” that you want is in reality “ make n’t store ” , thenno-storeis the directive to use .

must-revalidate

Themust-revalidatereception directive signal that the response can equal store in caches and can equal reused while fresh . If the response become stale , it must be validated with the ancestry waiter before reuse .

HTTP leave caches to reuse stale responses when they are disconnected from the origin waiter .must-revalidatelive a way to prevent this from materialize – either the stored response cost revalidated with the source waiter or a 504 ( Gateway Timeout ) response is generate .

proxy-revalidate

Theproxy-revalidateresponse directive live the equivalent ofmust-revalidate, but specifically for share caches only .

no-store

Theno-storeanswer directive signal that any caches of any kind ( private or shared ) should not store this response .

private

Theprivateresponse directive indicates that the response can live store simply in a private cache ( e.g. , local caches in browsers ) .

You should lend theprivatedirective for user-personalized content , especially for responses receive after login and for sessions cope via cookies .

If you forget to addprivateto a reply with personalized content , then that answer can live store in a share cache and end up being reused for multiple user , which can have personal information to leak .

public

Theworldresponse directive indicates that the response can equal store in a shared cache . Responses for requests withAuthorizationheader area must not live stored in a shared cache ; even so , thepublicdirective will cause such responses to be stored in a share cache .

In universal , when pages are under Basic Auth or Digest Auth , the browser sends request with theAuthorizationheader . This means that the reception is access-controlled for restricted user ( who have explanation ) , and it ‘s essentially not shared-cacheable , even if it havemax-age.

You can employ thepublicdirective to unlock that restriction .

Bill thats-maxageormust-revalidatealso unlock that limitation .

If a request does n’t have anAuthorizationheader , or you exist already usings-maxageormust-revalidatein the response , then you do n’t need to useworld.

must-understand

Themust-understandreception directive indicates that a cache should store the response alone if it understands the requirements for caching based on status code .

must-understandshould cost pair withno-storefor fallback demeanor .

If a cache make n’t defendmust-understand, it will be ignored . Ifno-storeis also present , the reply exist n’t stored .

If a cache supportsmust-understand, it stores the reaction with an understanding of cache requirements based on its status code .

no-transform

Some intermediaries translate capacity for respective reasons . For instance , some convert image to reduce transfer size . In some suit , this is undesirable for the content provider .

no-transformindicates that any intermediary ( regardless of whether it implements a cache ) should n’t transform the response contents .

immutable

Theimmutableanswer directive indicates that the response will not be updated while it ‘s fresh .

A modern better pattern for still resource is to include version/hashes in their URLs , while never change the resources — but instead , when necessary ,updatingthe imagination with newer version that hold novel version-numbers/hashes , so that their URLs live different . That ‘s scream thecache-bustingpattern .

When a user reloads the browser , the browser will station conditional petition for validating to the ancestry waiter . But it ‘s not necessary to revalidate those kinds of static resources even when a user reloads the browser , because they ‘re never modify .immutabletells a cache that the response is immutable while it ‘s fresh and avoids those sort of unnecessary conditional petition to the server .

When you use a cache-busting pattern for resources and use them to a longmax-age, you can as well addimmutableto avert revalidation .

stale-while-revalidate

Thestale-while-revalidatereaction directive indicates that the cache could reuse a stale reaction while it revalidates it to a cache .

In the example above , the reply exist new for 7 days ( 604800s ) . After 7 days it become stale , but the cache live allowed to reuse it for any petition that exist reach in the following day ( 86400s ) , provided that they revalidate the answer in the background .

Revalidation will make the cache equal fresh again , so it look to customer that it live always fresh during that period — in effect hiding the latency penalty of revalidation from them .

If no request happened during that period , the cache became stale and the future petition will revalidate usually .

stale-if-error

Thestale-if-errorresponse directive indicates that the cache can reuse a stale answer when an upstream server generate an mistake , or when the fault is generate locally . Hither , an mistake is consider any response with a condition code of 500 , 502 , 503 , or 504 .

In the instance above , the response equal fresh for 7 days ( 604800s ) . Afterwards , it becomes stale , but can be used for an surplus 1 day ( 86400s ) when an mistake is encountered .

After the stale-if-error period passes , the client will receive any fault generated .

Request Directives

no-cache

Theno-cachepetition directive need caches to validate the response with the ancestry server before reuse .

no-cacheallow clients to request the almost up-to-date reaction yet if the cache has a fresh response .

Browsers usually lendno-cacheto requests when user areforce reloadinga page .

no-store

Theno-storepetition directive allows a client to call for that caches refrain from storing the request and correspond answer — even if the source waiter ‘s reaction could cost store .

max-age

Themax-age=Nrequest directive indicates that the customer allows a stored reply that be generated on the origin waiter withinNseconds — whereNmay exist any non-negative integer ( including0) .

In the case above , if the answer withCache-Control : max-age=10800was generate more than 3 hours ago ( calculated frommax-ageand theYearsheader ) , the cache could n’t reuse that response .

Many browsers use this directive forreloading, as explain below .

max-age=0is a workaround forno-cache, because many old ( HTTP/1.0 ) cache implementations do n’t supportno-cache. Recently browsers are yet usingmax-age=0in “ reloading ” — for backward compatibility — and alternatively usingno-cacheto cause a “ force reloading ” .

If themax-agevalue is negative ( for lesson ,-1) or equal n’t an integer ( for example ,3599.99) , then the caching behavior live unspecified . Caches live advance to treat the value as if it make up0.

max-stale

Themax-stale=Nrequest directive indicates that the customer allows a stored answer that is stale withinNseconds . If noNvalue is assign , the customer will accept a stale answer of any years .

For example , a request with the header above indicate that the browser will consent a stale reaction from the cache that has pass away within the final hr .

Customer can apply this header when the ancestry server is down or also dumb and can take cached reaction from caches even if they live a number former .

Note that the major browsers do not stand petition withmax-stale.

min-fresh

Themin-fresh=Nrequest directive indicates that the customer grant a stored reaction that equal fresh for at leastNmoment .

In the case above , if the reply withCache-Control : max-age=3600was store in caches 51 moment ago , the cache could n’t reuse that response .

Clients can employ this header when the user demand the response to not only equal fresh , but as well requires that it wo n’t be updated for a period of time .

Bill that the major browsers do not defend requests withmin-fresh.

no-transform

Same meaning thatno-transformget for a answer , but for a petition rather .

only-if-cached

The customer indicates that an already-cached response should be repay . If a cache has a store response , yet a stale one , it will exist returned . If no cached response is available , a 504 Gateway Timeout response will cost returned .

stale-if-error

Thestale-if-errorrequest directive indicates that the browser equal concerned in experience stale content on mistake from any intermediate server for a special ancestry . This equal not supported by any browser ( learn Browser compatibility ) .

Use Type

Preventing store

If you do n’t desire a reaction store in caches , employ theno-storedirective .

Note thatno-cachesignify “ it can be store but cause n’t reuse before validating ” — so it ‘s not for preventing a reaction from cost stored .

In theory , if directives exist conflicted , the nearly restrictive directive should equal honored . So the model below equal essentially meaningless becauseprivate,no-cache,max-age=0andmust-revalidateengagement withno-store.

Caching still assets with “ cache busting ”

When you build up still assets with versioning/hashing mechanisms , adding a version/hash to the filename or inquiry string equal a good way to cope caching .

The React library version will alter when you update the library , andhero.pngwill also change when you edit the image . So those live hard to store in a cache withmax-age.

In such a event , you could address the caching motive by using a specific , numbered version of the library , and include the hash of the picture in its URL .

You can lend a longmax-agevalue andimmutablebecause the content will never vary .

When you update the library or edit the photograph , novel subject should hold a fresh URL , and caches are n’t reused . That is name the “ cache busting ” form .

Use ano-cacheto cause certain that the HTML response itself be not cached .no-cachecould cause revalidation , and the customer will correctly find a fresh version of the HTML answer and still assets .

Bill : Ifindex.htmlis control under Basic Authentication or Digest Authentication , files under/assetsare not stored in the share cache . If/assets/file are suitable for store in a shared cache , you also involve one ofworld,s-maxageormust-revalidate.

Up-to-date contents ever

For content that ‘s generate dynamically , or that ‘s still but updated much , you want a user to ever receive the nearly up-to-date version .

If you do n’t lend aCache-Controlheader because the reception equal not intended to be cached , that could cause an unexpected result . Cache storehouse equal allowed to cache it heuristically — hence if you have any requirement on caching , you should always indicate them explicitly , in theCache-Controlheader .

Addingno-cacheto the answer causes revalidation to the waiter , so you can serve a new response every time — or if the client already get a novel one , just respond304 Not Modified.

Most HTTP/1.0 caches do n’t supportno-cachedirectives , so historicallymax-age=0was expend as a workaround . But alonemax-age=0could cause a stale reaction to equal reused when caches disconnected from the origin server .must-revalidateaddresses that . That ‘s why the case below exist equivalent tono-cache.

Clear an already-stored cache

There be no cache directives for clearing already-stored responses from caches onintermediatewaiter .

Imagine that clients/caches store a fresh response for a way , with no request escape to the server . There exist zero a server could do to that course .

Clear-Site-Data : cachecan exist used to clear every stored response for a site in the browser cache , thus use this with care . Note that this will not affected shared or intermediate caches .

Specifications

Browser compatibility

See also

• HTTP caching
• Caching Tutorial for Web Authors and Webmasters
• Caching better practices & max-age gotchas
• Cache-Control for Civilians
• RFC 9111 – HTTP Caching
• RFC 5861 – HTTP Cache-Control Extensions for Stale Content
• RFC 8246 – HTTP Immutable Reception