Skip to content
Tutorials Center
My learning

Topics

Lesson 55 of 72 ยท Testing, Quality and Production

Performance and Caching

Make a Flask app faster with HTTP caching headers, ETags and 304 responses, an application cache, fewer database queries, indexes and profiling.

A Flask app is rarely slow because of Flask. It is slow because a page asks the database fifty questions, recomputes the same report for every visitor, or sends the same bytes again and again to a browser that already has them. Making an app fast is mostly about doing less work: skipping a request, skipping a computation or skipping a query.

This lesson goes from the outside in. First the browser and CDN (HTTP caching headers and conditional requests), then your own process (an application-level cache), then the database (query counts and indexes), and finally how to measure instead of guess.

flowchart LR
    B["Browser cache"] --> C["CDN / reverse proxy"]
    C --> A["App-level cache"]
    A --> D["Database"]

A request can be answered at any layer. The closer to the visitor, the cheaper it is.

Measure first

Optimizing without measuring wastes time. Before you change anything, find out where the time goes. We return to profiling at the end of this lesson; the short version is: count queries, time the slow endpoints, and fix the biggest cost first.

HTTP caching headers

HTTP has caching built in. Your response can tell browsers and shared caches (CDNs, proxies) how long to reuse it, and Flask's Response object has helpers for the header values.

The most important header is Cache-Control:

Directive Meaning
max-age=N The response may be reused for N seconds without asking the server
public Shared caches such as a CDN may store it
private Only the visitor's own browser may store it
no-cache May be stored, but must be revalidated before every reuse
no-store Do not store it at all (use for sensitive pages)

Public pages that are the same for everyone can be cached with public, max-age=.... Pages that depend on the logged-in user must be private or no-store, or one visitor's page could be served to another.

ETags and conditional requests

max-age has a weakness: when it expires, the browser downloads the whole page again, even if nothing changed. An ETag fixes that. It is a fingerprint of the response body. The browser stores it and sends it back in an If-None-Match header. If the fingerprint still matches, the server answers 304 Not Modified with no body, and the browser reuses its copy.

sequenceDiagram
    participant B as Browser
    participant S as Flask app
    B->>S: GET /info
    S-->>B: 200 + ETag + body
    Note over B: stores body and ETag
    B->>S: GET /info (If-None-Match: ETag)
    S-->>B: 304 Not Modified (no body)

A conditional request saves the bandwidth of the body, not the work of building it.

Flask can do this for you: response.add_etag() computes the fingerprint from the body, and response.make_conditional(request) compares it with the request headers and turns the response into a 304 when they match.

Python Cache-Control and conditional requests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second request sends the stored ETag and gets an empty 304. A client holding an outdated validator gets a fresh 200. Notice that Flask still ran the view and built the body before deciding on the 304. The saving is network traffic, not CPU. To skip the work as well, check a cheap validator (such as a row's updated_at) before building the page, or let a CDN answer the request.

Static files already get this treatment: Flask sends them with validators and the max-age you configure. Cache busting for CSS and JavaScript is covered in Static Files and Assets.

For fully public pages, a long max-age plus a CDN is the biggest speedup you can get. For pages that change often, use a short max-age or no-cache together with an ETag.

Caching inside the application

Sometimes the expensive part is not the network but the computation: a report built from a heavy query, a call to a slow API, a rendered sidebar. Instead of repeating it for every request, compute once and keep the result for a while, keyed by whatever makes the result unique.

The standard extension is Flask-Caching. It wraps a cache backend (in-process memory, Redis, Memcached, files) behind one API. It needs a real app setup and, in production, a Redis server, so this snippet is read-only:

Python
from flask import Flask
from flask_caching import Cache

app = Flask(__name__)
cache = Cache(app, config={"CACHE_TYPE": "SimpleCache", "CACHE_DEFAULT_TIMEOUT": 60})


@app.route("/top-products")
@cache.cached(timeout=300)
def top_products():
    return expensive_report()


@cache.memoize(timeout=60)
def price_for(product_id):
    return slow_price_lookup(product_id)

# After a product changes:
cache.delete_memoized(price_for, 42)

The idea is simple enough to build yourself. This runnable stand-in uses a fake clock so that the output is the same every time:

Python A time-limited cache in plain Python

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first visit to each category does the work; repeats are answered from the cache until 60 seconds pass or you clear it. Three things make real caching tricky:

  • Keys must include everything the result depends on. If the page differs per user, language or query string, those belong in the key, or one person sees another's data.
  • Invalidation. When the underlying data changes, delete the affected keys, or accept that the data may be up to timeout seconds stale.
  • Where it lives. A dictionary in memory belongs to one process. With four gunicorn workers you have four separate caches. A shared backend such as Redis gives all workers one cache.

Fewer, cheaper database queries

For most dynamic pages the database is the bottleneck, and the typical cause is the N+1 query problem: one query to get a list, then one more query per item to get its details. With 100 authors that is 101 round trips. A single JOIN (or an eager-loading option in your ORM, as in Relationships) fetches everything at once.

An index fixes the other classic problem. Without one, the database scans every row to find matches; with an index on the searched column it jumps straight to them. SQLite's EXPLAIN QUERY PLAN shows which strategy it will use.

Python Counting queries and checking indexes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

/slow runs six queries, /fast runs one, and both return the same JSON. The query plan starts with SCAN (read every row) before the index and SEARCH (jump to matching rows) after it. With five rows you won't feel a difference, but with five million you will.

A few more habits that pay off:

  • Select only the columns and rows you need; paginate lists instead of loading everything.
  • Add indexes for columns you filter, join and sort by, but not for every column: each index slows down writes.
  • Reuse database connections or use a connection pool instead of reconnecting on every request.
  • Keep slow work (sending email, generating PDFs) out of the request. See Async Views and Background Work.

Other quick wins

  • Compression. Serve HTML, CSS and JSON compressed (gzip or Brotli). Usually the web server or CDN does this, not Flask.
  • Static assets. Serve them from nginx or a CDN with long max-age values and fingerprinted file names.
  • Template work. Jinja caches compiled templates already. Avoid doing queries inside loops in templates.
  • Workers. Run several gunicorn workers so slow requests do not block each other (Deployment).

Profiling

When you do not know why a request is slow, ask Python. The standard cProfile module records every function call during a block of code. The report lists how often each function ran and how much time it took. Flask also ships a ready-made WSGI wrapper, werkzeug.middleware.profiler.ProfilerMiddleware, which prints a profile for every request in development (read-only here because it prints timings that change on every run).

Timings differ from run to run, but call counts do not, and call counts often reveal the problem on their own, such as a function that runs 200 times per request. The next example prints only counts.

Python Profiling a request with cProfile

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Once you know which function dominates, fix that one and measure again. A profile also tells you when something is not worth optimizing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which response header values are right for a page that shows the logged-in user's private data?

    private keeps shared caches from storing it, and no-store asks that nothing keep a copy. A public cache could otherwise serve one user's page to another.
  2. 2. What does a 304 Not Modified response tell the browser?

    The browser sent a validator (If-None-Match) that still matches, so the server skips the body and the browser reuses its stored copy.
  3. 3. You cache a function with an in-process dictionary and run 4 gunicorn workers. What happens?

    Each worker is a separate process with its own memory. To share cached values you need an external store such as Redis.
  4. 4. A page runs one query for the list of items and then one query per item. What is this called, and what is a usual fix?

    One query plus N per-item queries is the N+1 problem. Fetching related rows together with a JOIN or an eager-loading option removes the extra round trips.

Summary

  • Make the app do less work: skip the request, the computation or the query.
  • Cache-Control decides who may store a response and for how long; use private or no-store for user-specific pages.
  • ETags plus make_conditional() let the browser revalidate and receive a bodyless 304.
  • An application cache (Flask-Caching with Redis, or a small TTL cache) saves repeated computation; mind keys, invalidation and multiple workers.
  • Fix N+1 queries with joins or eager loading, and index the columns you search, join and sort by.
  • Measure with query counts and cProfile before and after every change.

Next, learn how to keep slow tasks out of the request in Async Views and Background Work.