Caching

The running example is the Bookshelf catalogue of books that grows across this section, in an app named catalog. This page needs only a small model, so that the cached work (a count, a title lookup) is real database work.

Source: Django: Models

CACHES is a dictionary of named caches. The alias default is mandatory: manage.py check fails with caches.E001 when it is missing. Each entry has a BACKEND (a dotted path to the cache class) and the common arguments in the table below. Other aliases are ordinary names that code or settings refer to, such as CACHE_MIDDLEWARE_ALIAS, cache_page(cache="…​") or the using argument of the template tag.

The scratch project defines one alias per backend. The local-memory default is the one the tests use; the others are shown in the sections that follow.

Source: Django: Settings - CACHES

The name template_fragments is not arbitrary: it is the alias the {% cache %} tag looks for first (see Template fragment caching). The project passes manage.py check and manage.py check --tag caches with this settings file.

No built-in backend is a database of record. Every one of them is allowed to forget a key at any moment (expiry, culling, eviction, a restart), so the code must always be able to rebuild the value.

The simplest use of the framework caches the entire site. Add two middleware classes, the "update" half first and the "fetch" half last:

Source: Django: The per-site cache

The three settings are CACHE_MIDDLEWARE_ALIAS (default 'default'), CACHE_MIDDLEWARE_SECONDS (default 600) and CACHE_MIDDLEWARE_KEY_PREFIX (default empty). The middleware caches GET and HEAD responses with status 200 whose request and response headers allow it; a HEAD request can be answered from a cached GET response because the middleware assumes both produce the same headers. Each distinct query string is a separate page. On the way out, UpdateCacheMiddleware adds Expires and a Cache-Control: max-age header so downstream caches follow the same lifetime. A view that sets its own max-age (for example through cache_control) overrides the site-wide number. When USE_I18N is true the key includes the active language, and when USE_TZ is true it includes the current time zone.

The scratch test ran a GET and then a POST through the pair:

The order is not a typo. FetchFromCacheMiddleware runs in the request phase, which goes top to bottom, and needs every header-varying middleware to have run so it can build the right key; so it goes after them. UpdateCacheMiddleware runs in the response phase, which goes bottom to top, and must see the final Vary header; so it goes before every middleware that adds to Vary (SessionMiddleware adds Cookie, GZipMiddleware adds Accept-Encoding, LocaleMiddleware adds Accept-Language). The general ordering rules are on Middleware.

The site-wide cache is only safe for content that is the same for everybody. It has no notion of "logged in" beyond the Vary: Cookie header that sessions add, so a site where most pages are personal should cache per view or per fragment instead.

cache_page from django.views.decorators.cache caches one view’s response for a number of seconds. Its signature is cache_page(timeout, *, cache=None, key_prefix=None):

Source: Django: The per-view cache

Like the per-site cache it is keyed off the full URL, so /foo/1/ and /foo/23/ are different entries, and the timeout wins over a max-age in the view’s own Cache-Control header (a behaviour that changed in Django 3.1). cache="special_cache" selects another alias from CACHES; key_prefix works like CACHE_MIDDLEWARE_KEY_PREFIX and is concatenated with the cache’s own KEY_PREFIX. cache_page also sets Cache-Control and Expires for downstream caches. Against runserver two requests gave one render and the headers below:

The identical render #1 and identical Expires show that the second response came from the cache. (Vary: Accept-Language is there because the scratch project enables LocaleMiddleware.)

For finer control, cache only the expensive piece of a template with the cache tag from the cache library. It takes at least two arguments, the timeout in seconds and a fragment name; the name is taken literally, never as a variable. A timeout of None caches forever, and the timeout may be a template variable that resolves to an integer.

Source: Django: Template fragment caching

Extra arguments after the name identify one cached copy each; here every user name gets its own profile fragment. They are converted to strings to build the key, so choose values that are unique as strings: None and "None" collide, and a model instance is risky because its __str__() need not be unique. request.user.username is unique for the default User model. If USE_I18N is on, the per-site cache respects the active language, but the tag does not: add a language variable (LANGUAGE_CODE from {% get_current_language as LANGUAGE_CODE %}) as a vary argument.

By default the tag stores fragments in the cache called template_fragments and falls back to default when no such alias exists. The using keyword, which must be the last argument, selects another cache; naming a cache that is not configured is an error. This explains a detail of the scratch project: the sidebar fragment, which has no using, lands in template_fragments because that alias exists, while the profile fragment lands in default. The test checks both stores:

make_template_fragment_key(fragment_name, vary_on=None) from django.core.cache.utils returns the key the tag uses, so Python code can delete or overwrite one fragment. The keys carry a readable prefix: make_template_fragment_key("sidebar") is template.cache.sidebar. followed by an MD5 digest of the vary_on values, and the digest changes with them. Delete from the same cache the tag used; deleting from the wrong alias is the classic reason a fragment "refuses" to update.

Source: Django: make_template_fragment_key()

The template engine itself is covered on Templates, and a different way to reuse template fragments, template partials, on Template Partials & HTMX; a partial reuses markup, it does not cache it.

When whole pages are too coarse, cache values. Any Python object that can be pickled safely can be stored: strings, dictionaries, lists of model instances. Reach the caches through django.core.cache:

The first of the two patterns in the scratch project is the cache-aside idiom in one call: get_or_set runs the callable only when the key is missing.

Source: Django: cache.get_or_set()

The second does it by hand, with a sentinel so that a cached None (a lookup that found nothing) counts as a hit; this is negative caching and stops repeated misses from hammering the database:

Source: Django: cache.get()

The tests confirmed the semantics one by one: add returns False for an existing key, incr/decr raise ValueError on a missing key, get_many omits keys that are absent, timeout=0 stores nothing and timeout=None stores forever, expiry is honoured, and the second call to get_book_title(999) ran with assertNumQueries(0). They also pinned the thread rule from the documentation:

Source: Django: Accessing the cache

Three cautions for the API. First, the value you get is a copy: the backends pickle on the way in, so mutating the returned list does not change the cached one; call set again. Second, there is no built-in protection against a cache stampede, many workers recomputing the same expired value at once; get_or_set does not lock. A common mitigation, which is a pattern and not a documented Django feature, is to take a short lock with cache.add("lock:name", "1", 30) (it returns False for every caller but the first) and have the others wait or serve slightly stale data; the scratch test checks only that add behaves that way. Third, never cache anything secret for a long time or under a guessable key on a cache that other tenants can reach.

The key you pass is not the key that reaches the backend. Django combines three parts, joined by colons by default:

Source: Django: Cache key transformation

Source: Django: Cache versioning

Memcached refuses keys longer than 250 characters and keys that contain whitespace or control characters. To keep code portable, the other built-in backends warn with CacheKeyWarning for such keys instead of failing, and so a key that works on locmem in development can break on Memcached in production. If your production backend accepts a wider range, silence the warning with warnings.simplefilter("ignore", CacheKeyWarning) in the management module of an installed app, or override validate_key() in a subclass of the backend and point BACKEND at it. Build keys from stable identifiers (f"book-title:{pk}"), never from user input of unbounded length, and hash anything long.

Source: Django: Cache key warnings

Since Django 4.0 BaseCache has an async twin of every method, named with an a prefix and taking the same arguments: aget, aset, aadd, aget_or_set, aget_many, aset_many, adelete, adelete_many, aclear, atouch, aincr, adecr, ahas_key, aincr_version, adecr_version and aclose. Use them in async def views, so the call does not block the event loop thread:

Source: Django: Asynchronous support

The curl run against runserver printed {"previous": 0, "has_key": true} and then {"previous": 1, "has_key": true}, and an AsyncClient test also covered aclear, aset_many, aget_many, aincr and adelete. Be clear about what "async" means here. The 6.1 documentation says Django has developing support for asynchronous cache backends and does not yet support truly asynchronous caching. In the installed 6.1.1 source the default async methods in BaseCache simply run the sync method through sync_to_async(…​, thread_sensitive=True), so the event loop is free while the cache call waits, at the price of a thread hop per call. The API will not change when native async backends arrive, so write the await form now. The decorators cache_control and never_cache also accept async def views (since Django 5.0). The general rules for async code are on the async page of this section.

Caching also happens outside your code: a proxy such as Squid, a CDN, an ISP cache (not possible under HTTPS) and, always, the visitor’s browser. You do not control them, but you can send hints in HTTP headers. The danger is that a cache that keys only on the URL can hand one visitor another visitor’s page, such as a logged-in inbox. The Vary response header lists the request headers that a cache must take into account when it builds its key. By default Django’s own cache builds keys from the fully qualified URL, so any variation by cookie, language or User-Agent must be declared.

Source: Django: Using Vary headers

vary_on_headers("User-Agent", "Cookie") varies on every combination of the listed headers; the names are case-insensitive. vary_on_cookie is shorthand for vary_on_headers("Cookie"). The decorators add to an existing Vary header, which is why they are preferable to setting response.headers["Vary"] by hand, which would overwrite what other code put there. patch_vary_headers(response, […​]) is the same helper for code that builds the response itself. The tests confirmed that the X-Client view renders twice for two different header values (and once for a repeat), and that the other two add Cookie to Vary.

A visitor meets two kinds of cache: the browser’s own, which is private, and a shared one belonging to a provider or a CDN, which is public. Some data must never reach a shared cache. Django’s decorators from django.views.decorators.cache set the matching headers:

Source: Django: Controlling cache - using other headers

cache_control accepts any valid Cache-Control response directive as a keyword (no_transform=True, must_revalidate=True, stale_while_revalidate=seconds, no_cache=True, …​). private and public are mutually exclusive, and the decorator removes the other one. Use django.utils.cache.patch_cache_control() for the same effect inside a view, for instance to mark anonymous responses public and signed-in responses private (always together with vary_on_cookie). never_cache adds headers so that browsers and shared caches do not store the response. The tests asserted these exact results:

Even without any server-side cache, @cache_control(max_age=3600) tells clients to reuse a response for an hour. If the cache middleware is also on, its max-age comes from CACHE_MIDDLEWARE_SECONDS and the decorator’s value takes precedence, with the headers merged correctly. For validation-based HTTP caching (ETag and Last-Modified, answered with 304 Not Modified), see the conditional view processing topic in the references. The cache_control directives are listed in the IANA registry; not all apply to responses.

Source: Django: Order of MIDDLEWARE

Everything above is the easy half. The cache is a copy, and a copy goes stale. Django offers no automatic dependency tracking between your models and the cache, so you choose a strategy per value. In rough order of preference:

Delete-on-change belongs where changes happen. A signal receiver on post_save and post_delete is the one place that sees every write, and the delete is scheduled with transaction.on_commit() so that a concurrent reader cannot re-cache the old rows between your write and the commit:

Source: Django: Performing actions after commit

The receiver must be connected when Django starts, so the app’s ready() imports the module (from . import services). The test that proves it uses TransactionTestCase, because a plain TestCase wraps each test in a transaction that never commits and so never runs on_commit hooks:

Source: Django: TransactionTestCase

Know the limits of this pattern. Signals do not fire for QuerySet.update(), bulk_create() or bulk_update(), nor for raw SQL, so those need an explicit invalidation call. A page cached with cache_page or the per-site middleware has no key your code knows (it is made of URL, headers and prefixes), which is a strong reason to prefer short timeouts for those, or to use key_prefix and bump it. The signals themselves, transactions and on_commit are covered on "Transactions, Raw SQL & Multiple Databases".

Tests that touch the cache must not depend on what an earlier test left behind. Three habits keep them honest:

The scratch suite ran all of the above in a single command, with this result:

Source: Django: Testing tools

The same suite also ran the file backend (in a temporary directory), the database backend (after createcachetable), the dummy backend and the culling behaviour of locmem with MAX_ENTRIES of 6 and CULL_FREQUENCY of 2. Testing as a topic has its own page in this section.

The four books consulted for this section were written for Django 1.11 to 3.x, and each treats caching briefly or by way of an example. These are the points where a reader following them today would go wrong, as of 2026-10-03:

On 5.2 LTS the same code works, except for the 6.1-only key and DatabaseCache changes above and the Authorization vary, which is documented as arriving in 6.0.6 (check the 5.2 documentation for your patch release). As of 2026-10-03 the documentation still describes native asynchronous cache backends as future work.