{"id":6252,"library":"starlette-compress","title":"Starlette Compress","description":"Starlette Compress is a fast and simple ASGI middleware for Starlette and FastAPI applications that provides response compression. It supports Zstandard (Zstd), Brotli, and GZip algorithms and offers more sensible defaults compared to Starlette's built-in GZipMiddleware. Currently at version 1.7.0, the library is actively maintained and aims for semantic versioning compliance.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/Zaczero/pkgs/tree/main/starlette-compress","tags":["starlette","fastapi","middleware","compression","gzip","brotli","zstd","asyncio","web performance"],"install":[{"cmd":"pip install starlette-compress","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core ASGI framework dependency.","package":"starlette","optional":false},{"reason":"Required for Brotli compression support.","package":"brotli","optional":false},{"reason":"Required for Zstandard (Zstd) compression support.","package":"zstandard","optional":false},{"reason":"Alternative Brotli implementation, often listed as a dependency alongside 'brotli'.","package":"brotlicffi","optional":false}],"imports":[{"symbol":"CompressMiddleware","correct":"from starlette_compress import CompressMiddleware"}],"quickstart":{"code":"from starlette.applications import Starlette\nfrom starlette.middleware import Middleware\nfrom starlette.responses import PlainTextResponse\nfrom starlette.routing import Route\nfrom starlette_compress import CompressMiddleware\n\nasync def homepage(request):\n    return PlainTextResponse(\"This is a sample response that will be compressed if larger than 500 bytes.\")\n\nroutes = [\n    Route(\"/\", endpoint=homepage),\n]\n\nmiddleware = [\n    Middleware(CompressMiddleware, minimum_size=100) # Set a lower minimum_size for demonstration\n]\n\napp = Starlette(routes=routes, middleware=middleware)\n\n# To run this example, save it as app.py and execute: uvicorn app:app --port 8000\n# Then test with curl -H \"Accept-Encoding: gzip, deflate, br, zstd\" http://localhost:8000/","lang":"python","description":"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."},"warnings":[{"fix":"Initialize middleware with `CompressMiddleware(minimum_size=N)` where N is your desired minimum size in bytes. E.g., `minimum_size=100` for smaller responses.","message":"Responses 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adjust `zstd_level`, `brotli_quality`, and `gzip_level` parameters during middleware initialization. For example, `CompressMiddleware(zstd_level=6, brotli_quality=6, gzip_level=6)`.","message":"Default 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Import `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\")`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure only one layer of compression middleware is active in your application stack. Disable other compression mechanisms if `starlette-compress` is used.","message":"Running `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `remove_accept_encoding=True` during middleware initialization if you want the `Accept-Encoding` header removed after compression: `CompressMiddleware(remove_accept_encoding=True)`.","message":"By 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to 3.9 or higher before upgrading to Starlette 1.0.0 (and consequently ensuring `starlette-compress` compatibility).","message":"Starlette, 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.","severity":"breaking","affected_versions":"Starlette >=1.0.0rc1"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}