How to Handle File Upload in FastAPI: Simple Guide

In FastAPI, handle file uploads by using the File and UploadFile classes from fastapi. Define an endpoint that accepts a file parameter typed as UploadFile, then read or save the file content inside the function.

Why This Happens

Beginners often try to accept file uploads using plain str or bytes parameters, which FastAPI does not recognize as files. This causes errors or empty uploads because FastAPI expects special types to handle multipart form data.

python

from fastapi import FastAPI

app = FastAPI()

@app.post("/upload")
async def upload_file(file: str):
    return {"filename": file}

Output

422 Unprocessable Entity error: value is not a valid file

The Fix

Use UploadFile from fastapi to receive files properly. It provides file metadata and async methods to read the file content. Also, use File() to tell FastAPI this parameter is a file upload.

python

from fastapi import FastAPI, File, UploadFile

app = FastAPI()

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    content = await file.read()
    return {"filename": file.filename, "content_size": len(content)}

Output

{"filename": "example.txt", "content_size": 1234}

Prevention

Always use UploadFile with File() for file uploads in FastAPI. Validate file size and type as needed. Use async reading to avoid blocking. Test uploads with tools like curl or Postman to confirm correct behavior.

Related Errors

Common related errors include:

• 422 Unprocessable Entity: Happens when the file parameter is missing or wrongly typed.
• File too large: Can occur if the server or client limits are exceeded; configure limits accordingly.
• Incorrect content type: Ensure the client sends multipart/form-data for file uploads.

Key Takeaways

Use UploadFile and File() from fastapi to handle file uploads correctly.

Read file content asynchronously with await file.read() to avoid blocking.

Validate file metadata like filename and size for safer handling.

Test file uploads with proper multipart/form-data requests.

Avoid using plain str or bytes parameters for file uploads in FastAPI.