Install & Compatibility
Where this runs
tested against v1.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.287s · 39.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 0.266s · 49MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CompressMiddleware
✓ from starlette_compress import CompressMiddleware
This example demonstrates how to integrate `CompressMiddleware` into a Starlette application. The middleware automatically compresses responses based on the client's `Accept-Encoding` header, provided the response meets the minimum size requirement.
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import PlainTextResponse
from starlette.routing import Route
from starlette_compress import CompressMiddleware
async def homepage(request):
return PlainTextResponse("This is a sample response that will be compressed if larger than 500 bytes.")
routes = [
Route("/", endpoint=homepage),
]
middleware = [
Middleware(CompressMiddleware, minimum_size=100) # Set a lower minimum_size for demonstration
]
app = Starlette(routes=routes, middleware=middleware)
# To run this example, save it as app.py and execute: uvicorn app:app --port 8000
# Then test with curl -H "Accept-Encoding: gzip, deflate, br, zstd" http://localhost:8000/
Debug
Known issues
gotchaResponses must be at least 500 bytes by default to be compressed. This is an optimization to prevent CPU overhead for minimal bandwidth savings. If you expect smaller responses to be compressed, adjust the `minimum_size` parameter.fixInitialize middleware with `CompressMiddleware(minimum_size=N)` where N is your desired minimum size in bytes. E.g., `minimum_size=100` for smaller responses.
affects: All versions
gotchaDefault compression levels are set to 4 for all algorithms. Higher levels result in smaller files but require more CPU and time, while lower levels are faster but produce larger files. Tune these based on your performance and bandwidth needs.fixAdjust `zstd_level`, `brotli_quality`, and `gzip_level` parameters during middleware initialization. For example, `CompressMiddleware(zstd_level=6, brotli_quality=6, gzip_level=6)`.
affects: All versions
gotchaThe middleware compresses a predefined set of content-types. If your application serves custom content-types (e.g., `application/x-my-format`), they will not be compressed by default. You must explicitly add them.fixImport `add_compress_type` and call it with your custom content-type: `from starlette_compress import add_compress_type; add_compress_type("application/my-custom-type")`. affects: All versions
gotchaRunning `starlette-compress` alongside another compression middleware (e.g., Starlette's built-in `GZipMiddleware`, an ASGI server's compression, or another framework's middleware) can lead to double compression, which is inefficient and may cause errors or corrupted responses.fixEnsure only one layer of compression middleware is active in your application stack. Disable other compression mechanisms if `starlette-compress` is used.
affects: All versions
gotchaBy default, the `Accept-Encoding` header remains intact after `starlette-compress` has processed the request. This can sometimes lead to issues if downstream middleware or the application itself attempts to re-negotiate or apply further compression based on this header.fixSet `remove_accept_encoding=True` during middleware initialization if you want the `Accept-Encoding` header removed after compression: `CompressMiddleware(remove_accept_encoding=True)`.
affects: All versions
breakingStarlette, the underlying framework for `starlette-compress`, now requires Python 3.9+ for versions 1.0.0 and above. While `starlette-compress` also requires Python 3.9+, older Starlette applications on Python 3.8 or earlier will break when upgrading Starlette, potentially impacting `starlette-compress` compatibility.fixUpgrade your Python environment to 3.9 or higher before upgrading to Starlette 1.0.0 (and consequently ensuring `starlette-compress` compatibility).
affects: Starlette >=1.0.0rc1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'starlette_compress'
The `starlette-compress` library is either not installed or there's a typo in the import statement.
fixEnsure the library is installed using `pip install starlette-compress` and the import path is correct: `from starlette_compress import CompressMiddleware`.
RuntimeError: Brotli support is not installed. Install with 'pip install brotli-sdist'
You are attempting to use Brotli compression, but the optional `brotli-sdist` dependency is not installed.
fixInstall the required package for Brotli support: `pip install brotli-sdist`.
RuntimeError: Zstandard support is not installed. Install with 'pip install python-zstandard'
You are attempting to use Zstandard (Zstd) compression, but the optional `python-zstandard` dependency is not installed.
fixInstall the required package for Zstandard support: `pip install python-zstandard`.
TypeError: CompressMiddleware.__init__ missing 1 required positional argument: 'app'
The `CompressMiddleware` class was instantiated without providing the ASGI application instance it needs to wrap.
fixPass your Starlette or FastAPI application instance as the first argument when initializing the middleware: `app.add_middleware(CompressMiddleware, app=app)`.
Upgrade
Version history
1.7.1latest on PyPI · released May 10, 2026
Audit
Dependencies
starletterequiredCore ASGI framework dependency.
brotlirequiredRequired for Brotli compression support.
zstandardrequiredRequired for Zstandard (Zstd) compression support.
brotlicffirequiredAlternative Brotli implementation, often listed as a dependency alongside 'brotli'.