Skip to main content

django-http-compression

https://img.shields.io/github/actions/workflow/status/adamchainz/django-http-compression/main.yml.svg?branch=main&style=for-the-badge https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge https://img.shields.io/pypi/v/django-http-compression.svg?style=for-the-badge https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge pre-commit

Django middleware for compressing HTTP responses with Zstandard, Brotli, or Gzip.

For a bit of background, see the introductory blog post.


Work smarter and faster with my book Boost Your Django DX which covers many ways to improve your development experience.


Requirements

Python 3.11 to 3.15 supported.

Django 5.2 to 6.1 supported.

From Python 3.14, Zstandard support requires libzstd to be linked into Python. (uv’s Python distributions include it on Unix.) If it isn’t, the middleware falls back to backports.zstd if that’s installed, and otherwise disables Zstandard, using the other codings.

Installation

  1. Install with pip:

    python -m pip install django-http-compression

To include Brotli support, add the brotli extra to pull in the brotli package:

python -m pip install 'django-http-compression[brotli]'

Most browsers support Zstandard (MDN), but you may want to include Brotli as an option for clients that do not.

  1. Add django-http-compression to your INSTALLED_APPS:

    INSTALLED_APPS = [
        ...,
        "django_http_compression",
        ...,
    ]
  2. Add the middleware:

    MIDDLEWARE = [
        ...,
        "django_http_compression.middleware.HttpCompressionMiddleware",
        ...,
    ]

    The middleware should be above any that may modify your HTML, such as those of django-debug-toolbar or django-browser-reload. Remove any other middleware that will encode your responses, such as Django’s GZipMiddleware.

API

django_http_compression.middleware.HttpCompressionMiddleware

This middleware is similar to Django’s GZipMiddleware, but with extra coding support. It compresses responses with one of three codings, depending on what the client supports per the request’s Accept-Encoding header:

  • Zstandard (zstd).

  • Brotli (br), if the brotli extra is installed.

  • Gzip (gzip). The legacy alias x-gzip is also accepted, per RFC 9110 Section 8.4.1.3.

See the MDN content-encoding documentation for more details on these codings and their browser support.

Codings are prioritized based on any q factors sent by the client, for example accept-encoding: gzip;q=1.0, br;q=0.9 will prefer gzip over Brotli. After that, the middleware prefers the algorithms in the order of the above list, with Zstandard being the most preferred. This is because it’s the most performant, offering similar compression to Brotli in about half the time (per CloudFlare’s testing).

In practice, modern browsers do not send q factors and nearly all support Zstandard, so that will generally be selected.

Each coding uses a compression level chosen to balance speed against size:

To change these, subclass the middleware and set the corresponding attributes:

from django_http_compression.middleware import HttpCompressionMiddleware


class CompressionMiddleware(HttpCompressionMiddleware):
    zstandard_compression_level = 5  # -131072 to 22, higher is smaller but slower
    brotli_compression_quality = 5  # 0 to 11
    gzip_compression_level = 5  # 1 to 9

Then use your subclass in MIDDLEWARE in place of HttpCompressionMiddleware.

The middleware skips compression if any of the following are true:

  • The status code is 1xx, 204, or 304, since these responses can’t have content. 304 responses still get Vary: accept-encoding, to match the 200 response they stand in for (RFC 9110 Section 15.4.5).

  • The content-type header does not match a known-compressible type like text/html.

  • The content body is less than 50 bytes.

  • The response already has a Content-Encoding header.

  • The response is a partial response, with status code 206, since byte ranges refer to the encoded content (RFC 9110 Section 14.4).

  • The request does not have a supported accept-encoding header.

  • Compression lengthens the response (for non-streaming responses).

If the response has an etag header, the etag is made weak to comply with RFC 9110 Section 8.8.1.

If a compressed response has an accept-ranges header, it’s removed, since byte ranges refer to the compressed content, which isn’t stable (RFC 9110 Section 14.3).

The middleware mitigates some attacks using the Heal the Breach (HTB) technique, like Django’s GzipMiddleware does. This technique adds some random padding to responses: an x-noise header with a random token containing between 0 and 99 bytes long, Base64-encoded. This padding makes it much harder for attackers to infer the contents of the response by measuring its compressed size while modifying some input, for example by trying to guess an embedded session token character-by-character. To change the maximum number of random bytes added to responses, subclass the middleware and set the max_random_bytes attribute.

History

Django has supported Gzip compression since before version 1.0, from this commit (2005). Since then, compression on the web has evolved in Brotli (2013) and Zstandard (2015), with browsers adding support for both.

Brotli support on Python has always required a third-party package, making it a little inconvenient. But with Python 3.14 adding Zstandard support to the standard library, it’s much easier to support a modern, efficient compression algorithm.

This project exists as an evolution of Django’s GZipMiddleware, with the aim to provide a base for adding (at least) Zstandard support to Django itself. It pulls inspiration from the django-compression-middleware package.

Metadata

Release files for django-http-compression 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-http-compression 1.5.0
File Size Uploaded Provenance Actions
django_http_compression-1.5.0.tar.gz 11.7 kB With provenance Details for django_http_compression-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-http-compression 1.5.0
File Interpreter ABI Platform Actions
django_http_compression-1.5.0-py3-none-any.whl Python 3 none any Details for django_http_compression-1.5.0-py3-none-any.whl

Total release size: 23.6 kB

Release files / django_http_compression-1.5.0.tar.gz

Download URL django_http_compression-1.5.0.tar.gz
Size 11.7 kB
Tags Source
SHA-256 checksum
How to use checksums
76c27173eb02e045c61f964c008db431d37d4e855333d25a92bd0899fb0c1f16
BLAKE2b-256 checksum
How to use checksums
e5fef6430e7c38e8e7830d7ebd43ef9594ebf1f31193261636d0701d597a243c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / django_http_compression-1.5.0-py3-none-any.whl

Download URL django_http_compression-1.5.0-py3-none-any.whl
Size 12.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3adfc53e7167c59be9dfdd4ba22893596f8de33baadf86a93db45ef50165c8bf
BLAKE2b-256 checksum
How to use checksums
79dae92cb3a9cabd87f26399989ba9e443a701683f76f0a4bddd4a992824f99e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for django-http-compression 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for django_http_compression-1.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page