FastAPI's StreamingResponse: Send Data in Chunks

Why it exists

Standard HTTP responses require the server to know the full content and its size before sending anything. For very large files or dynamically generated content, this means holding the entire response in memory, which is slow, resource-intensive, and can lead to server crashes.

The mental model

Think of it like a garden hose versus a bucket. A normal response is like filling a huge bucket (the server's memory) with data and then dumping it all at once on the client. A StreamingResponse is like turning on the hose; data flows immediately and continuously, without needing a bucket at all. The server just passes chunks along as they become available.

How it works

StreamingResponse takes a generator function or an iterator. In a FastAPI path operation, you write a function that uses yield to produce chunks of data (as bytes or strings). FastAPI iterates over your generator, sending each yielded chunk to the client as part of the HTTP response body. The connection stays open until the generator is exhausted, typically using HTTP's chunked transfer encoding.

When to use it

Use StreamingResponse when the response body is too large to fit comfortably in memory or is generated over time. This is perfect for serving large file downloads (CSVs, logs, videos), streaming audio, or piping the live output from a service like an AI Large Language Model. It dramatically improves the time-to-first-byte for the client.

When not to use it

Avoid it for small, self-contained data, especially structured data like a typical JSON object. A standard JSONResponse is simpler and more efficient for these cases. If you need to stream structured JSON, consider using a format like JSON Lines, where each line is a valid JSON object.

One canonical example

A common use is serving a large video file from disk. Instead of reading the entire multi-gigabyte file into memory, you can write a generator that reads the file in small chunks (e.g., 1MB at a time) and yields each chunk. The user's browser can start playing the video almost instantly while the rest of the file continues to stream in the background, all while your server's memory usage remains minimal.