Serving Non-JSON Responses

Serving Files on Disk with FileResponse

The most direct way to offer a file for download is when the file already exists on your server's disk. For this, FastAPI provides the FileResponse class. It's efficient because it streams the file from the disk to the client without loading the entire file into memory first.

Let's watch a short video that walks through the fundamental usage of FileResponse.

As you saw, the basic implementation is simple:

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get("/cat-image")
async def get_cat_image():
    return FileResponse("path/to/your/cat.jpg")

However, there are a few important considerations for production-ready code.

Handling Missing Files

What happens if the file at the specified path doesn't exist? The application will raise an unhandled server error. To prevent this, you should always check if the file exists before attempting to serve it.

By performing this check, you can return a clean 404 Not Found error instead of a generic 500 Internal Server Error, which is much better practice.

Forcing a Download vs. Displaying Inline

When you return a FileResponse, the browser has to decide what to do with it. If it's an image, PDF, or text file, the default behavior is often to display it directly in the browser window (an "inline" display). If you want to force the browser to prompt the user to save the file, you need to set the Content-Disposition header to attachment.

FileResponse makes this easy with the filename parameter.

Here’s a summary of the behavior:

• return FileResponse("path/to/file.jpg"): Browser will likely display the image. The response header will be Content-Disposition: inline.
• return FileResponse("path/to/file.jpg", filename="cute_cat.jpg"): Browser will prompt the user to download a file named cute_cat.jpg. The response header will be Content-Disposition: attachment; filename="cute_cat.jpg".

You can also explicitly set the media_type (also known as MIME type, e.g., image/jpeg, application/pdf) in the FileResponse to help the browser, though FastAPI is quite good at inferring it from the file extension.

Streaming Large or Generated Data with StreamingResponse

FileResponse is perfect for existing files, but what if you need to serve a file that's too large to handle at once, or one that you need to generate on the fly?

This is a common scenario in backend development. For example:

• Exporting a large CSV report from millions of database records.
• Generating a ZIP archive of multiple files.
• Streaming a video file.

Loading the entire content into memory before sending the response is inefficient and can easily crash your server. The solution is StreamingResponse. It takes an iterator (or an async iterator) and sends the data to the client piece by piece, keeping memory usage low and constant.

This is the direct FastAPI equivalent of Django's StreamingHttpResponse.

Streaming a Large File from Disk

Let's start by using StreamingResponse to do what FileResponse does, but more explicitly, to understand the mechanism. We'll create a generator function that reads a large file in chunks.

The key pattern is:

1. Define a generator function that yields data in chunks.
2. Pass an instance of this generator to StreamingResponse.
3. Because standard file operations (open, read) are blocking, the path operation function should be defined with def, not async def. FastAPI is smart enough to run this synchronous code in a thread pool to avoid blocking the event loop.

If you need maximum concurrency, you can use a library like aiofiles to perform asynchronous file reads. The article from OneUptime has an excellent example of this.

Generating a CSV Report On-the-Fly

The true power of StreamingResponse is realized when generating content dynamically. Imagine exporting user data from your database to a CSV file.

This pattern is incredibly powerful:

• Low Time to First Byte (TTFB): The client receives the CSV header immediately, even before the first database query is complete.
• Constant Memory Usage: The server's memory usage is only proportional to the batch size, not the entire dataset.
• Scalability: You can export massive datasets that would be impossible to handle in memory.

FileResponse vs. StreamingResponse: A Quick Comparison

Here's a summary to help you decide which to use.

This table is adapted from the "Comparison of Approaches" in the OneUptime article.

Conclusion

In this lesson, you've learned how to make your FastAPI applications serve more than just JSON. By mastering FileResponse and StreamingResponse, you can build APIs that handle file downloads, large data exports, and other complex response types with efficiency and control.

Key Takeaways:

• FileResponse is for serving existing static files. It's simple and automatically handles many details. Use the filename parameter to force a download.
• StreamingResponse is for large or dynamically generated data. It uses a generator to send data in chunks, keeping memory usage low and constant.
• Control Browser Behavior with Headers: The Content-Disposition header (attachment vs. inline) is crucial for controlling whether a file is downloaded or displayed.
• Async vs. Sync Matters: Use def for path operations with blocking I/O (like standard open()), and async def for non-blocking I/O (like with aiofiles).

Preview of the Next Lesson:

This lesson concludes the "Advanced Features and Concurrency" module. You've built a solid foundation in creating sophisticated FastAPI services. Now, how do you ensure they are reliable and correct?

The next module, "Testing and Production Deployment," will teach you just that. We'll kick it off by learning how to write synchronous and asynchronous tests for your API endpoints using TestClient and httpx.AsyncClient.