Performance & Optimization

"Performance" is not one number. A faster page can use more memory, a smaller database load can mean more Python work, and your own time is more expensive than CPU time. Before changing anything, write down what you are optimising and how you will know it improved: the median and 95th-percentile response time of one URL, the number of queries per page, requests per second under a load test, memory per worker. Then follow the same loop every time.

Django’s guide adds one rule that applies before any tool: work at the appropriate level. The database is better at counting and filtering than Python, and Python is faster than the template language. The three ways of counting the Bookshelf catalogue below give the same number, but at very different cost:

count() sends one SELECT COUNT(*); len() loads 20,000 rows into model instances just to count them; the template filter does the same plus template overhead. The guide notes the exception: if the page will loop over the rows anyway, len() on the already-evaluated queryset costs nothing extra — which is why measuring the real page beats rules of thumb.

Source: Performance and optimization: work at the appropriate level, Database access optimization

The "latest books" page lists the 50 most recently published books with their authors. The naive view does not mention authors at all; the template does, one row at a time:

The URLconf routes /books/naive/ and /books/ to the two views; a seed_books management command fills the database with 200 authors and 20,000 books using bulk_create().

Source: Database access optimization: retrieve related objects efficiently, QuerySet.select_related()

Different tools answer different questions. Use them from the outside in: first which page is slow, then which part of that page (database, Python, templates), then which function.

The profiles above point at the most common Django performance problem: the N+1 query pattern, where a loop touches a relation that was not loaded and Django fetches it one row at a time. The fixes, all covered in depth in Query Optimization & Fetch Modes, are to load the relation up front with select_related() (a SQL join, for foreign keys and one-to-one fields) or prefetch_related() (a second query, for many-to-many and reverse relations), or — new in Django 6.1 — to change the queryset’s fetch mode so that the first lazy load fetches the relation for every instance that came from the same queryset. Measured on the running example, reading book.author.name for 50 books:

Even against an in-process SQLite file the explicit join is about 13 times faster than the default; across a network the gap grows with every round trip. FETCH_PEERS is a good safety net for code you do not control, and FETCH_RAISE turns any accidental lazy load into an exception, which is a cheap way to find N+1 patterns in tests. On Django 5.2 LTS only select_related() and prefetch_related() are available. The same page covers the other query-level tools: only()/defer(), values(), iterator(), exists(), count(), update()/bulk_create() and doing work in the database with expressions instead of Python loops.

Source: Database access optimization, Fetch modes

Once the number of queries is right, look at the slow ones. An index lets the database find rows without scanning the whole table, at the price of extra disk space and slower writes, so add indexes for the filters and orderings your pages actually use and check that the database uses them. QuerySet.explain() prints the plan for any queryset. The Bookshelf archive page filters books by year and rating and sorts by date:

SCAN books_book means a full-table scan of all 20,000 rows, followed by a temporary sort. Declaring an index in the model’s Meta and generating a migration fixes both:

The __year lookup became a range condition on the index, the sort disappeared (the index is already ordered), and the query got 3.6 times faster on a small table. On PostgreSQL, explain(analyze=True) runs the query and reports real row counts and timings. Foreign keys get an index automatically, and unique=True creates one; everything else — composite, partial (condition=), functional and covering (include=) indexes, and PostgreSQL’s GIN/GiST/BRIN types — is described in Constraints, Indexes & Composite Keys and PostgreSQL & Database Backends. On a large production table, create indexes concurrently (PostgreSQL’s AddIndexConcurrently operation) so the migration does not lock writes.

Source: QuerySet.explain(), Model index reference, Database access optimization: use standard DB optimization techniques

By default Django opens a database connection the first time a request needs one and closes it when the request ends (CONN_MAX_AGE = 0). Opening a connection — TCP, TLS, authentication, a backend process on PostgreSQL — can cost more than the queries themselves, especially on virtualised hosts. Two mechanisms avoid paying it on every request.

Persistent connections (CONN_MAX_AGE set to a number of seconds, or None for no limit) keep each worker thread’s connection open between requests. CONN_HEALTH_CHECKS (Django 4.1) makes Django check a reused connection once per request before using it, so a database restart costs no failed request. To see the difference, the running example logs every new connection with the connection_created signal and is served by one Gunicorn sync worker:

Persistent connections have caveats spelled out in the databases reference: each thread holds its own connection, so the database must allow at least as many connections as you have worker threads in total; the development server starts a new thread per request, so the setting has no effect there; and under ASGI persistent connections should be disabled — the reference recommends the database backend’s own connection pooling instead.

Connection pooling (Django 5.1, PostgreSQL with psycopg 3 only) keeps a pool of open connections per database alias per process and hands one to whichever thread needs it; closing a Django connection returns it to the pool. It is the recommended option under ASGI and works under WSGI too. Install psycopg[pool] and set "pool" in OPTIONS to True (the ConnectionPool defaults) or to a dict of ConnectionPool arguments. CONN_MAX_AGE must stay 0; connection lifetime is set with the pool’s max_lifetime option instead:

Size the pool so that max_size times the number of processes stays below the server’s max_connections. An external pooler such as PgBouncer in transaction mode is the alternative when many application servers share one database; it needs DISABLE_SERVER_SIDE_CURSORS = True in the database settings. The details are in PostgreSQL & Database Backends.

Source: Databases: persistent connections, Databases: connection pool, Databases: transaction pooling and server-side cursors, connection_created signal, psycopg: connection pools

Caching saves the result of expensive work so the next request can reuse it. The guide is explicit that it is one of the final steps, not a substitute for fixing badly written code: a cached N+1 page is still an N+1 page on every cache miss and after every invalidation. Think of caching as layers, from closest to the user to closest to the data, and use the outermost layer that the content’s freshness rules allow:

Every layer above "one object" needs a real shared backend in production — django.core.cache.backends.redis.RedisCache (built in since Django 4.0) or PyMemcacheCache — because the default local-memory cache is per process. The Bookshelf project uses LocMemCache here only because no Redis server was available for the examples. A per-view cache turns the 51-query page into zero queries on a hit, and cached_property runs its query once per instance; both are pinned down by the other two tests of the suite run earlier:

The hard part of caching is not storing values but deciding when they are wrong: choose a timeout per kind of data, invalidate on writes (signals or explicit cache.delete() in the service that changes the data), version keys when the format changes, and never cache a response that contains one user’s data under a key shared by everyone. All of that, plus Redis configuration, fragment caching and the async cache API, is in Caching; the session engines are compared in Sessions, Cookies, Messages & Signing.

Source: Performance and optimization: caching, Django’s cache framework, cached_property, Using cached sessions

Rendering a Django template has two costs: compiling the template file into a node tree, and rendering that tree with a context. The cached template loader removes the first cost after the first use by keeping compiled templates in memory. Older advice says to enable it in production; since Django 4.1 it is the default whenever OPTIONS["loaders"] is not set — with DEBUG = False and with DEBUG = True, where the autoreloader clears it when a template changes. The engine reports its loaders directly:

So the only way to lose the cache is to set loaders explicitly without wrapping them in django.template.loaders.cached.Loader. The second cost depends on how the template is written. The guide notes that {% block %} is faster than {% include %} and that heavily fragmented templates cost more. A small benchmark of the list page, once with the row inline and once with each row in an included books/book_row.html, shows both effects:

Loading the template drops from tens of microseconds to almost nothing with the cache, and including a template 50 times inside a loop made the render about 1.7 times slower than writing the row inline. Neither number matters next to 51 queries — which is the point: fix queries first, then look at templates only if the profiler says so. When it does, the usual causes are logic in the template (method calls that hit the database, nested loops, heavy filters) that belongs in the view, and deep include/inclusion-tag nesting. Template partials (Django 6.0, {% partialdef %}) keep reusable fragments in the same file without a separate include lookup; see Template Partials & htmx. Jinja2 renders faster than the Django template language and Django supports it as a second backend, but the guide recommends it only after the other options are exhausted, and it changes the template syntax. The engine and its options are covered in Templates.

Source: Performance and optimization: template performance, The cached template loader, Django 4.1 release notes: templates

Two built-in middleware classes reduce what goes over the wire. Their place in MIDDLEWARE matters: on the way out, responses pass through the list from bottom to top, so GZipMiddleware must sit above anything that reads or writes the body (it compresses last), and ConditionalGetMiddleware goes right below it so its ETag is computed on the uncompressed content:

GZipMiddleware compresses responses for clients that send Accept-Encoding: gzip, skipping bodies under 200 bytes and responses that already have a Content-Encoding. Compressing HTML that mixes secrets (a CSRF token, personal data) with text an attacker can influence exposes it to the BREACH family of attacks; since Django 4.2 the middleware applies the "Heal The Breach" mitigation, adding up to max_random_bytes (default 100) random bytes to each compressed response, and it makes any ETag weak, as RFC 9110 requires for a transformed body. ConditionalGetMiddleware adds an ETag to responses that lack one and answers If-None-Match or If-Modified-Since with an empty 304 Not Modified. The running example under Uvicorn shows all of it:

The page shrank from 2,354 to roughly 600 bytes, and two identical requests produced different compressed lengths (632 and 565) — that is the random padding at work. The revalidation returned no body at all. Note what it did not save: ConditionalGetMiddleware computes the ETag from the finished response, so the view still ran its query and rendered the template. To skip that work too, give the view a cheap way to decide freshness with the last_modified(), etag() or condition() decorators; here one aggregate query replaces the whole page:

(Book gained an updated_at = models.DateTimeField(auto_now=True) field for this.) In production the reverse proxy or CDN usually compresses responses, often with Brotli as well as gzip, which removes the need for GZipMiddleware and keeps the CPU work off the Python workers; enable one or the other, not both. Middleware ordering in general is explained in Middleware, and BREACH together with the CSRF token’s own masking in Security.

Source: GZip middleware, Conditional GET middleware, Conditional view processing, Django 4.2 release notes: mitigation for the BREACH attack

Static files never change between deployments, so the fastest request for one is the request the browser never makes. Django’s ManifestStaticFilesStorage makes that safe: collectstatic copies each file under a name that contains a hash of its content (site.c9ede0bebe98.css) and the {% static %} tag emits that name, so a changed file gets a new URL and old copies can be cached "forever". WhiteNoise builds on it with CompressedManifestStaticFilesStorage, which also writes gzip and (with the Brotli package installed) Brotli versions of each file at build time, and with a middleware that serves them from the Python process with far-future cache headers for hashed names:

WhiteNoiseMiddleware goes directly after SecurityMiddleware, as in the middleware list of the previous section.

The 23 KB stylesheet goes out as 733 bytes of Brotli, compressed once at deploy time instead of on every request, and the hashed URL may be cached for ten years; the unhashed name gets only 60 seconds, which is why templates must always use {% static %} rather than hard-coded paths. Because these headers are correct, putting a CDN in front is a settings change: point the CDN at the site as its origin and set DJANGO_STATIC_HOST, and every {% static %} URL moves to the CDN while the CDN fetches each file from WhiteNoise once:

The alternative is to upload collectstatic output to object storage (S3 and similar, through django-storages) that the CDN serves directly. Minifying CSS and JavaScript is better done by the front-end build tool (esbuild, Vite and the like) before collectstatic than by a Django package at request time. User-uploaded media need the same thinking but cannot be served by WhiteNoise. All of this is covered in Static Files & Front-End Assets and File Uploads & Storage.

Source: ManifestStaticFilesStorage, Performance and optimization: static files, WhiteNoise: using WhiteNoise with Django

Async views do not make Python code or database queries faster. They help when a request spends most of its time waiting — on other HTTP services, on a slow API, on a long-poll or a stream — because an ASGI server can serve other requests while one waits, and because one view can wait for several things at the same time. The Bookshelf price comparison asks three partner shops for a price; each call takes about half a second (simulated here with asyncio.sleep):

Writing async def alone changed nothing — the sequential version still takes the sum of the three waits; the gain comes from asyncio.gather(). A real implementation would use an async HTTP client (HTTPX, aiohttp) with timeouts. The rules that keep async from making things slower:

The async model, sync_to_async/async_to_sync, async-safe middleware and the async ORM are covered in Async Support.

Source: Asynchronous support: performance, Asynchronous support: async views

Every optimisation on this page removes work from one stage of the path a request travels (the full path is in Request/Response Cycle). The earlier a stage answers, the more work it saves:

Source: Performance and optimization, Django’s cache framework: downstream caches

Source: Performance and optimization, FAQ: how can I see the raw SQL queries Django is running?

Two Scoops of Django 1.11 (2017), chapter 24 "Finding and Reducing Bottlenecks", is still a sound checklist — measure with the debug toolbar, cut query counts with select_related()/prefetch_related(), assert query counts in tests, index what you filter and sort on, read query plans, keep logs and ephemeral data out of the relational database, cache with Memcached or Redis, use a CDN. Its advice that ATOMIC_REQUESTS rarely needs to be turned off for speed also still holds (see Transactions, Raw SQL & Multiple Databases). The tools it names have moved on:

The book’s "ephemeral data" advice needs one nuance: Django’s default message storage keeps messages in a cookie, with the session as fallback, not in the database, and the cached_db session engine gives cache-speed reads while keeping sessions durable.

Source: Django’s cache framework: Memcached, Django’s cache framework: Redis, MESSAGE_STORAGE, django-extensions: RunProfileServer

The Django rows come from the release notes of each version; the package rows from their PyPI pages and documentation.

Source: Django 4.1 release notes, Django 4.2 release notes, Django 5.1 release notes, Django 6.1 release notes