How to Use Gzip Middleware in FastAPI for Response Compression

To use GZipMiddleware in FastAPI, import it from fastapi.middleware.gzip and add it to your app with app.add_middleware(GZipMiddleware). This middleware compresses responses larger than a default size, improving bandwidth and speed.

Syntax

The GZipMiddleware is added to a FastAPI app using app.add_middleware(). You can optionally set minimum_size to control the smallest response size (in bytes) that will be compressed.

• app: Your FastAPI application instance.
• GZipMiddleware: Middleware class that compresses responses using gzip.
• minimum_size: Optional integer to set the minimum response size for compression (default is 500 bytes).

python

from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware

app = FastAPI()

app.add_middleware(GZipMiddleware, minimum_size=1000)

Example

This example shows a FastAPI app with GZipMiddleware added. It returns a large JSON response that will be compressed automatically if the client supports gzip encoding.

python

from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware

app = FastAPI()
app.add_middleware(GZipMiddleware)

@app.get("/items")
async def read_items():
    # Large response to trigger compression
    return {"items": ["item" + str(i) for i in range(1000)]}

Output

When you request GET /items with a client that sends header 'Accept-Encoding: gzip', the response is compressed with gzip, reducing data size.

Common Pitfalls

• Not adding GZipMiddleware before defining routes can cause it to not compress responses.
• Setting minimum_size too high may prevent compression for smaller responses.
• Clients must send Accept-Encoding: gzip header to receive compressed responses.
• Compressing already compressed content (like images) wastes CPU and should be avoided.

python

from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware

# Wrong: Adding middleware after route definitions (middleware might not apply)
app = FastAPI()

@app.get("/data")
async def data():
    return {"data": "some large data"}

app.add_middleware(GZipMiddleware)

# Right: Add middleware before routes

app = FastAPI()
app.add_middleware(GZipMiddleware)

@app.get("/data")
async def data():
    return {"data": "some large data"}

Quick Reference

Feature	Description	Default
GZipMiddleware	Middleware to compress responses with gzip	N/A
minimum_size	Minimum response size in bytes to compress	500
Client Header	Client must send 'Accept-Encoding: gzip' to get compressed response	Required
Placement	Add middleware before route definitions	Best practice

Key Takeaways

Add GZipMiddleware to your FastAPI app using app.add_middleware before defining routes.

Set minimum_size to control when responses get compressed; default is 500 bytes.

Clients must send 'Accept-Encoding: gzip' header to receive compressed responses.

Avoid compressing small or already compressed content to save CPU.

Gzip middleware improves bandwidth and speeds up response delivery for large payloads.