Metadata-Version: 2.4
Name: django-http-compression
Version: 1.5.0
Summary: Django middleware for compressing HTTP responses with Zstandard, Brotli, or Gzip.
Keywords: Django
Author: Adam Johnson
Author-email: Adam Johnson <me@adamj.eu>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Requires-Dist: asgiref>=3.6
Requires-Dist: backports-zstd>=1 ; python_full_version < '3.14'
Requires-Dist: django>=5.2
Requires-Dist: typing-extensions>=4.1
Requires-Dist: brotli>=1.0.1 ; extra == 'brotli'
Requires-Python: >=3.11
Project-URL: Changelog, https://github.com/adamchainz/django-http-compression/blob/main/CHANGELOG.rst
Project-URL: Funding, https://adamj.eu/books/
Project-URL: Repository, https://github.com/adamchainz/django-http-compression
Provides-Extra: brotli
Description-Content-Type: text/x-rst

=======================
django-http-compression
=======================

.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/django-http-compression/main.yml.svg?branch=main&style=for-the-badge
   :target: https://github.com/adamchainz/django-http-compression/actions?workflow=CI

.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
  :target: https://github.com/adamchainz/django-http-compression/actions?workflow=CI

.. image:: https://img.shields.io/pypi/v/django-http-compression.svg?style=for-the-badge
  :target: https://pypi.org/project/django-http-compression/

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
   :target: https://github.com/psf/black

.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
   :target: https://github.com/pre-commit/pre-commit
   :alt: pre-commit

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

For a bit of background, see the `introductory blog post <https://adamj.eu/tech/2025/10/10/introducing-django-http-compression/>`__.

----

**Work smarter and faster** with my book `Boost Your Django DX <https://adamchainz.gumroad.com/l/byddx>`__ 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 <https://github.com/facebook/zstd>`__ to be linked into Python.
(uv’s Python distributions include it on Unix.)
If it isn’t, the middleware falls back to `backports.zstd <https://pypi.org/project/backports.zstd/>`__ if that’s installed, and otherwise disables Zstandard, using the other codings.

Installation
------------

1. Install with **pip**:

   .. code-block:: sh

       python -m pip install django-http-compression

  To include Brotli support, add the ``brotli`` extra to pull in the `brotli <https://pypi.org/project/Brotli/>`__ package:

  .. code-block:: sh

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

  Most browsers support Zstandard (`MDN <https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding#browser_compatibility>`__), but you may want to include Brotli as an option for clients that do not.

2. Add django-http-compression to your ``INSTALLED_APPS``:

   .. code-block:: python

       INSTALLED_APPS = [
           ...,
           "django_http_compression",
           ...,
       ]

3. Add the middleware:

   .. code-block:: python

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

   The middleware should be *above* any that may modify your HTML, such as those of `django-debug-toolbar <https://django-debug-toolbar.readthedocs.io/>`__ or `django-browser-reload <https://pypi.org/project/django-browser-reload/>`__.
   Remove any other middleware that will encode your responses, such as Django’s |GZipMiddleware|__.

   .. |GZipMiddleware| replace:: ``GZipMiddleware``
   __ https://docs.djangoproject.com/en/stable/ref/middleware/#django.middleware.gzip.GZipMiddleware

API
---

``django_http_compression.middleware.HttpCompressionMiddleware``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This middleware is similar to Django’s |GZipMiddleware2|__, 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:

.. |GZipMiddleware2| replace:: ``GZipMiddleware``
__ https://docs.djangoproject.com/en/stable/ref/middleware/#django.middleware.gzip.GZipMiddleware

.. |accept-encoding| replace:: ``Accept-Encoding``
__ https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding

* 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 <https://www.rfc-editor.org/rfc/rfc9110#section-8.4.1.3>`__.

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

.. |the MDN content-encoding documentation| replace:: the MDN ``content-encoding`` documentation
__ https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding

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 <https://blog.cloudflare.com/new-standards/#introducing-zstandard-compression>`__).

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:

* Zstandard: level 3, zstd’s default, which `CloudFlare also uses <https://blog.cloudflare.com/new-standards/#introducing-zstandard-compression>`__.
* Brotli: quality 4, `as CloudFlare uses <https://blog.cloudflare.com/results-experimenting-brotli/>`__.
* Gzip: level 6, like Django’s ``GZipMiddleware``.

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

.. code-block:: python

    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 <https://www.rfc-editor.org/rfc/rfc9110#section-6.4.1-8>`__.
  304 responses still get ``Vary: accept-encoding``, to match the 200 response they stand in for (`RFC 9110 Section 15.4.5 <https://www.rfc-editor.org/rfc/rfc9110#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 <https://www.rfc-editor.org/rfc/rfc9110#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 <https://datatracker.ietf.org/doc/html/rfc9110.html#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 <https://www.rfc-editor.org/rfc/rfc9110#section-14.3>`__).

The middleware mitigates some attacks using the `Heal the Breach (HTB) technique <https://ieeexplore.ieee.org/document/9754554>`__, 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 <https://github.com/django/django/commit/8fd94405b51298e84fea604f339b8147df583270>`__ (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 <https://pypi.org/project/django-compression-middleware/>`__.
