File responses in FastAPI

Introduction

File responses let your web app send files like images or documents to users. This helps users download or view files directly from your app.

When you want users to download a report or PDF from your website.

To send images or videos stored on your server to users.

When serving static files like manuals or guides through your API.

To allow users to download generated files like CSV exports.

When you want to stream large files without loading them fully in memory.

Syntax

FastAPI

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get("/file")
async def get_file():
    return FileResponse("path/to/your/file.txt")

Use FileResponse to send files from your server to the client.

The file path must be accessible by your app and include the full or relative path.

Examples

Sends a PDF file named report.pdf located in the /files folder.

FastAPI

return FileResponse("/files/report.pdf")

Sends a JPEG image and explicitly sets the media type for the browser to understand the file type.

FastAPI

return FileResponse("images/photo.jpg", media_type="image/jpeg")

Sends a text file but suggests the browser save it as UserManual.txt.

FastAPI

return FileResponse("docs/manual.txt", filename="UserManual.txt")

Sample Program

This example creates a FastAPI app with one route /download-report. When visited, it sends the report.pdf file from the files folder. The browser will download it as AnnualReport.pdf.

FastAPI

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get("/download-report")
async def download_report():
    # Sends the report.pdf file to the user
    return FileResponse("./files/report.pdf", media_type="application/pdf", filename="AnnualReport.pdf")

Important Notes

Make sure the file path is correct and the file exists to avoid errors.

Use media_type to help browsers handle the file correctly.

Setting filename controls the name users see when downloading.

Summary

File responses let your app send files to users easily.

Use FileResponse with the file path to send files.

Set media type and filename for better user experience.

Practice

1. What is the main purpose of FileResponse in FastAPI?

easy

A. To send files from the server to the client

B. To upload files from the client to the server

C. To delete files on the server

D. To read file contents as text

Solution

1. Step 1: Understand the role of FileResponse

   FileResponse is designed to send files from the server to the client in FastAPI.

2. Step 2: Differentiate from other file operations

   Uploading or deleting files are handled differently; FileResponse specifically sends files.

3. Final Answer:

   To send files from the server to the client -> Option A

4. Quick Check:

   FileResponse sends files [OK]

Hint: FileResponse is for sending files to users [OK]

Common Mistakes:

• Confusing FileResponse with file upload handling
• Thinking FileResponse reads file content as text
• Assuming FileResponse deletes files

2. Which of the following is the correct way to import FileResponse in FastAPI?

easy

A. from fastapi.responses import file_response

B. from fastapi import FileResponse

C. import FileResponse from fastapi.responses

D. from fastapi.responses import FileResponse

Solution

1. Step 1: Recall correct import syntax

   FastAPI's FileResponse is imported from fastapi.responses using Python's standard import syntax.

2. Step 2: Check each option's correctness

   from fastapi.responses import FileResponse uses correct syntax and casing. from fastapi import FileResponse misses the submodule. import FileResponse from fastapi.responses uses wrong syntax. from fastapi.responses import file_response uses wrong casing.

3. Final Answer:

   from fastapi.responses import FileResponse -> Option D

4. Quick Check:

   Correct import is from fastapi.responses [OK]

Hint: Import FileResponse from fastapi.responses [OK]

Common Mistakes:

• Using wrong import syntax like 'import X from Y'
• Importing directly from fastapi without .responses
• Wrong casing like file_response instead of FileResponse

3. What will the following FastAPI endpoint return?

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get('/download')
async def download_file():
    return FileResponse('example.pdf', media_type='application/pdf', filename='report.pdf')

medium

A. Returns JSON with file path 'example.pdf'

B. Sends the file 'example.pdf' with download name 'report.pdf' and PDF media type

C. Raises an error because filename cannot be set

D. Sends 'report.pdf' file ignoring 'example.pdf'

Solution

1. Step 1: Analyze FileResponse parameters

   The first argument is the file path to send ('example.pdf'). The media_type sets the content type to PDF. The filename sets the suggested download name.

2. Step 2: Understand the endpoint behavior

   When called, the endpoint sends the file 'example.pdf' with content type 'application/pdf' and suggests the name 'report.pdf' for download.

3. Final Answer:

   Sends the file 'example.pdf' with download name 'report.pdf' and PDF media type -> Option B

4. Quick Check:

   FileResponse sends file with given path and filename [OK]

Hint: FileResponse(path, media_type, filename) sends file with custom name [OK]

Common Mistakes:

• Thinking filename argument changes the file read
• Expecting JSON response instead of file
• Assuming filename cannot be set

4. Identify the error in this FastAPI endpoint that tries to send a file:

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get('/file')
async def get_file():
    return FileResponse(filepath='data.txt', media_type='text/plain')

medium

A. FileResponse does not accept a 'filepath' keyword argument

B. The media_type 'text/plain' is invalid

C. FileResponse requires a filename argument

D. The endpoint must be synchronous, not async

Solution

1. Step 1: Check FileResponse constructor parameters

   FileResponse expects the file path as the first positional argument, not as a 'filepath' keyword argument.

2. Step 2: Identify the error cause

   Passing 'filepath=' causes a TypeError because FileResponse does not have a 'filepath' parameter.

3. Final Answer:

   FileResponse does not accept a 'filepath' keyword argument -> Option A

4. Quick Check:

   FileResponse needs file path as first argument, no 'filepath=' [OK]

Hint: FileResponse takes file path as first argument, no 'filepath=' keyword [OK]

Common Mistakes:

• Using 'filepath=' keyword instead of positional argument
• Thinking filename is mandatory
• Believing async is not allowed for endpoints

5. You want to create a FastAPI endpoint that sends a file only if it exists, otherwise returns a 404 error. Which code snippet correctly implements this behavior?

hard

A. from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get('/download')
async def download():
return FileResponse('file.txt')

B. from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get('/download')
async def download():
try:
return FileResponse('file.txt')
except FileNotFoundError:
return {'error': 'File missing'}

C. from fastapi import FastAPI, HTTPException
from fastapi.responses import FileResponse
import os

app = FastAPI()

@app.get('/download')
async def download():
if os.path.exists('file.txt'):
return FileResponse('file.txt')
else:
raise HTTPException(status_code=404, detail='File not found')

D. from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get('/download')
async def download():
if 'file.txt' in os.listdir('.'):
return FileResponse('file.txt')
else:
return {'error': 'File not found'}

Solution

1. Step 1: Check file existence properly

   Using os.path.exists('file.txt') correctly checks if the file exists before sending.

2. Step 2: Return appropriate response on missing file

   Raising HTTPException with 404 status is the proper way to signal file not found in FastAPI.

3. Final Answer:

   Code snippet B correctly checks file existence and raises 404 if missing -> Option C

4. Quick Check:

   Check file with os.path.exists + raise HTTPException [OK]

Hint: Check file with os.path.exists, raise HTTPException 404 if missing [OK]

Common Mistakes:

• Not checking file existence before sending
• Returning JSON error instead of raising HTTPException
• Using try-except without proper exception handling