Skip to main content

Configurable middleware to add HTTP caching headers for URL's.

Project description

Django Cache Headers



Django Cache Headers allows you to set HTTP caching headers for URL patterns according to certain policies. It does not perform any caching itself - it merely sets the headers on the response which are then interpreted by eg. Varnish.

Doing a truly zero-conf Varnish turned out to be fragile, so Django Cache Headers now generates a VCL file that can be included into or adapted to your default Varnish configuration file.


  1. Install or add django-cache-headers to your Python path.
  2. Add cache_headers to your INSTALLED_APPS setting.
  3. Add cache_headers.middleware.CacheHeadersMiddleware before SessionMiddleware and AuthenticationMiddleware and MessageMiddleware to your MIDDLEWARE_CLASSES setting.


Django Cache Headers provides four caching policies. You may define your own policies.:

  1. all-users - response is marked as cached once for all users.
  2. anonymous-only - response is marked as cached once only for anonymous users.
  3. anonymous-and-authenticated - response is marked as cached once for anonymous users and once for authenticated users.
  4. per-user - response is marked as cached once for anonymous users and for each authenticated user individually.


The timeouts key combines the policy, timeout in seconds and URL regexes in a nested dictionary:

    "timeouts": {
        "all-users": {
            60: (
        "anonymous-only": {
            60: (
        "anonymous-and-authenticated": {
            60: (
        "per-user": {
            60: (
        "custom-policy": {
            60: (

Set browser-cache-seconds to specify how long the browser may cache a response before it has to revalidate with the server. It defaults to 5 seconds.:

CACHE_HEADERS = {"browser-cache-seconds": 10}

Set enable-tampering-checks to enable checks that guard against cache poising by tampering with the cookies. Keep this disabled for most unit tests. Unit test’s client.login() does not trigger the normal expected login path.

CACHE_HEADERS = {“enable-tampering-checks”: True}

Varnish configuration

Generate the VCL snippet:

python generate_vcl > /path/to/generated.vcl

Save the contents of sample.vcl as /etc/varnish/default.vcl. Restart Varnish for the configuration to take effect.


Praekelt Consulting

  • Hedley Roos
  • Altus Barry



  1. Django 2.0 and Python 3 compatibility. Django 1.9 support has been dropped.


  1. Fix anonymous-only policy to consider isauthenticated cookie.


  1. Ensure isauthenticated cookie expires at end of session if session is set to do so.


  1. An anonymous user may in fact have a session. Handle this case gracefully.


  1. Added vcl generation management command, to be used in tandem with varnish. sample.vcl updated to reflect usage.
  2. Make use of on_user_auth_event to ensure no-cache header is set during login and logout.
  3. Extra protection against tampered session cookie.
  4. Policies no longer makes an assumption on the session cookie name.


  1. Iterate over regexes in order of most specific (longest) to least specific (shortest).
  2. Revert OrderedDict change since it is not required anymore due to the above change.


  1. Use an OrderedDict for guaranteed policy iteration order.


  1. Ignoring cookies completely when setting headers turned out to be a mistake due to too many security concerns. Restore them.


  1. Handle case where user may also be logged in and a cookie not being set.


  1. Use the s-maxage header for compatability with Varnish.


  1. Leave response untouched if status code is not 200.


  1. Initial release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-cache-headers, version 0.4
Filename, size File type Python version Upload date Hashes
Filename, size django_cache_headers-0.4-py2.7.egg (33.4 kB) File type Egg Python version 2.7 Upload date Hashes View
Filename, size django-cache-headers-0.4.tar.gz (15.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page