FastAPI Streaming & File Responses: Stop Loading Everything Into Memory

Most FastAPI tutorials show you returning a list of dictionaries or a Pydantic model. That works fine for a JSON API returning 100 users. But the moment you try to return a 2GB CSV export or stream a live video feed, your server falls over. Memory spikes, workers crash, and you're debugging at 2 AM why your container got OOM-killed. The problem isn't FastAPI — it's that you're buffering the entire response in memory before sending a single byte. StreamingResponse and FileResponse are the tools that fix this. By the end of this article, you'll know exactly when to use each, how to avoid the common pitfalls that burn production systems, and how to serve large data without breaking a sweat.

Why You Shouldn't Return a List When You Can Stream

The default FastAPI response pattern — return a list or dict, let it serialize to JSON — works by building the entire response body in memory before sending. For small payloads, this is fine. For large ones, it's a disaster. Every concurrent request doubles memory usage. At 100 concurrent requests for a 500MB CSV, you're looking at 50GB RAM. StreamingResponse lets you send data as it's produced. The client sees the first bytes almost instantly, and your server memory stays flat regardless of response size. The trade-off is that you lose automatic Content-Length headers and error handling becomes trickier — if the stream fails mid-way, the client gets a truncated response. But for large datasets, video, or real-time data, there's no alternative.

# io.thecodeforge — Python tutorial

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv
import io

app = FastAPI()

async def generate_csv_rows():
    # Simulate a database cursor yielding rows
    for i in range(1000000):
        yield f"{i},user_{i}@example.com,active\n"

@app.get("/export/users")
async def export_users():
    # StreamingResponse takes an async generator or iterable
    # Content-Type is set manually; no Content-Length unless you know it
    return StreamingResponse(
        generate_csv_rows(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=users.csv"}
    )

FileResponse: The OS Does the Heavy Lifting

When you need to serve a static file from disk, FileResponse is your friend. It uses the operating system's sendfile syscall to transfer data directly from the file descriptor to the network socket, bypassing Python's memory entirely. This means zero copy — the file never enters your application's memory space. For large files (videos, ISOs, logs), this is orders of magnitude more efficient than reading the file into a bytes object and returning it. FileResponse also automatically handles range requests for partial content, enabling pause/resume downloads and video seeking. The catch: it only works with actual files on disk, not dynamically generated content. And it blocks the event loop if the file is on a slow filesystem (NFS, network mounts) — use it with async file I/O or offload to a thread pool.

# io.thecodeforge — Python tutorial

from fastapi import FastAPI
from fastapi.responses import FileResponse
import os

app = FastAPI()

@app.get("/download/{filename}")
async def download_file(filename: str):
    file_path = f"/data/uploads/{filename}"
    if not os.path.exists(file_path):
        return {"error": "File not found"}, 404
    # FileResponse automatically sets Content-Type, Content-Length, and handles Range headers
    return FileResponse(
        path=file_path,
        filename=filename,  # Override the download name
        media_type="application/octet-stream"  # Force download
    )

Streaming JSON: Don't Wait for the Whole Array

Returning a large JSON array as a single Response forces the client to wait for the entire serialization to complete. For paginated APIs, this is fine. But for real-time dashboards or log streams, you want to send JSON objects as they become available. The trick is to use StreamingResponse with a generator that yields JSON-encoded objects separated by newlines (JSON Lines format) or as a continuous array. The client can parse each line as it arrives. This is how Twitter's streaming API works. The downside: standard JSON parsers expect a complete document. You'll need a streaming JSON parser on the client side (e.g., ijson for Python, or JSON.parse on each line in JavaScript).

# io.thecodeforge — Python tutorial

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import json
import asyncio

app = FastAPI()

async def event_stream():
    # Simulate a stream of events from a queue
    for i in range(10):
        event = {"id": i, "message": f"Event {i}"}
        yield json.dumps(event) + "\n"
        await asyncio.sleep(0.5)

@app.get("/events")
async def stream_events():
    return StreamingResponse(
        event_stream(),
        media_type="application/x-ndjson"  # Newline-delimited JSON
    )

When Streaming Breaks: The Gotchas You'll Hit

StreamingResponse isn't magic. It has sharp edges. First, if your generator raises an exception mid-stream, the client gets a truncated response with no error indication. Always wrap generator logic in try/except and log errors. Second, without a Content-Length, proxies like Nginx or Cloudflare may buffer the entire response before forwarding it to the client, negating the memory benefit. Set the X-Accel-Buffering: no header for Nginx, or disable buffering in your reverse proxy. Third, streaming is incompatible with some middleware that reads the entire body (e.g., compression middleware). If you need compression, compress chunks yourself. Finally, async generators must not perform blocking I/O — use async libraries or run blocking calls in a thread pool.

# io.thecodeforge — Python tutorial

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import logging

logger = logging.getLogger(__name__)

app = FastAPI()

async def safe_generator():
    try:
        for i in range(100):
            if i == 50:
                raise ValueError("Simulated failure at row 50")
            yield f"row {i}\n"
    except Exception as e:
        logger.error(f"Stream failed at row {i}: {e}")
        # Yield an error message so client knows something went wrong
        yield f"\nERROR: {e}\n"

@app.get("/export/unsafe")
async def export_unsafe():
    return StreamingResponse(safe_generator(), media_type="text/plain")

FileResponse vs StreamingResponse: When to Use Which

FileResponse is for static files on disk. It's zero-copy, handles range requests, and sets Content-Type automatically. Use it for serving uploaded files, static assets, or any file that exists before the request. StreamingResponse is for dynamically generated content: database query results, real-time data, or data that doesn't exist as a file. It gives you full control over the output format and timing. The rule of thumb: if the data is already on disk, use FileResponse. If you're generating it on the fly, use StreamingResponse. Never read a file into memory just to return it as a Response — that's the classic rookie mistake that costs you memory.

Production Patterns: Rate Limiting and Backpressure

Streaming responses can overwhelm clients or downstream services if you produce data faster than they can consume it. In a production system, you need backpressure. One pattern is to use an asyncio.Queue with a max size: if the queue is full, the producer waits. Another is to yield chunks at a controlled rate using asyncio.sleep(). For file downloads, the OS's TCP stack provides natural backpressure — sendfile blocks when the socket buffer is full. But for generated streams, you must implement it yourself. I've seen a logging pipeline crash a Kafka cluster because the producer streamed events faster than the broker could ingest them. The fix was to add a sliding window that limited the number of outstanding unacknowledged events.

# io.thecodeforge — Python tutorial

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio

app = FastAPI()

async def rate_limited_stream():
    queue = asyncio.Queue(maxsize=10)
    
    async def producer():
        for i in range(1000):
            await queue.put(f"event {i}\n")
            # Producer waits if queue is full
        await queue.put(None)  # Sentinel
    
    async def consumer():
        while True:
            item = await queue.get()
            if item is None:
                break
            yield item
    
    asyncio.create_task(producer())
    async for chunk in consumer():
        yield chunk

@app.get("/stream/backpressure")
async def stream_with_backpressure():
    return StreamingResponse(rate_limited_stream(), media_type="text/plain")

When Not to Stream: The Case for Simple Responses

Streaming is not free. It adds complexity: error handling, missing Content-Length, proxy buffering issues, and client-side parsing requirements. If your response fits comfortably in memory (say, under 10MB), just return a normal Response. The overhead of setting up a generator and managing the stream isn't worth it. Also, if your API consumers expect a complete JSON document (most do), streaming JSON requires them to use a streaming parser. For internal APIs where both sides are under your control, streaming is fine. For public APIs, stick with pagination or standard responses unless you have a clear need for low latency or huge payloads.