FastAPI File Uploads and Form Data

Handling file uploads is a core requirement for most production APIs, yet it's where many FastAPI applications leak memory or open security holes. FastAPI's avails UploadFile and Form to stream multipart payloads without buffering entire requests in RAM, but the defaults hide pitfalls around optional files, path traversal, and missing python-multipart that will bite you at scale.

How FastAPI Handles File Uploads and Form Data

FastAPI uses the UploadFile class and Form dependency to parse multipart/form-data requests. Unlike JSON bodies, form data mixes text fields with binary file streams. FastAPI reads the raw request body, splits it by the MIME boundary, and exposes each part as a Python object. UploadFile wraps a SpooledTemporaryFile, meaning small files stay in memory while large ones spill to disk automatically. This avoids loading entire files into RAM, which is critical for handling multiple concurrent uploads. The default threshold is 1 MB — files above that go to disk. Form fields are parsed as simple strings or coerced to declared types. FastAPI does not buffer the entire request before processing; it streams the parts as they arrive. This means you can start validating fields and writing file chunks before the upload finishes. In practice, this gives you O(1) memory per connection for file data, limited only by disk I/O. You must declare form fields with Form(...) and file fields with File(...) — omitting these will cause FastAPI to interpret the parameter as a JSON body, resulting in a 422 validation error.

Uploading a Single File with Validation

The UploadFile class is a wrapper around a Python SpooledTemporaryFile. This is critical for performance: it keeps small files in RAM for speed but offloads larger files to the temporary directory of your OS to prevent memory exhaustion. In production, always validate the content_type and enforce a maximum file size.

from fastapi import FastAPI, UploadFile, File, HTTPException, status
import shutil
from pathlib import Path

app = FastAPI()
UPLOAD_DIR = Path("uploads")
UPLOAD_DIR.mkdir(exist_ok=True)

@app.post('/upload')
async def upload_document(file: UploadFile = File(...)):
    # 1. MIME Type Validation (Don't trust the extension!)
    if file.content_type not in ['application/pdf', 'image/jpeg']:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST, 
            detail="Invalid file type. Only PDF and JPEG are allowed."
        )

    # 2. Size Validation using file object metadata
    # Note: .size is available in newer FastAPI/Starlette versions
    MAX_SIZE = 10 * 1024 * 1024  # 10MB
    real_file_size = 0
    
    # Stream content to disk to avoid memory spikes
    save_path = UPLOAD_DIR / file.filename
    with open(save_path, "wb") as buffer:
        while chunk := await file.read(1024 * 1024):  # Read in 1MB chunks
            real_file_size += len(chunk)
            if real_file_size > MAX_SIZE:
                raise HTTPException(status_code=413, detail="File too large")
            buffer.write(chunk)

    return {
        'filename': file.filename,
        'saved_at': str(save_path),
        'final_size': real_file_size
    }

Mixing Form Fields with File Uploads

A frequent pain point for developers is trying to send a Pydantic JSON body alongside a file. Due to the way HTTP works, you cannot easily mix application/json and multipart/form-data. Instead, you must declare each form field using Form(). FastAPI will then parse the multipart body and map the keys to your arguments.

from fastapi import FastAPI, UploadFile, File, Form, status
from typing import Annotated

app = FastAPI()

@app.post('/forge/profile-update', status_code=status.HTTP_201_CREATED)
async def update_profile(
    username: Annotated[str, Form(...)],
    bio: Annotated[str, Form(min_length=10)],
    # Optional file: defaults to None if not in the request
    avatar: UploadFile | None = File(None) 
):
    response = {
        "user_id": 1024, 
        "username": username, 
        "bio": bio,
        "avatar_received": False
    }
    
    if avatar:
        # Process avatar (e.g., upload to S3 or resize)
        response["avatar_received"] = True
        response["avatar_name"] = avatar.filename
        
    return response

Handling Multiple File Uploads

FastAPI natively supports multiple files under the same field name by declaring the parameter as a list of UploadFile. The client sends each file with the same key, and FastAPI collects them into a Python list. This is common for batch uploads, image galleries, or attachment-heavy workflows.

from fastapi import FastAPI, UploadFile, File, HTTPException

app = FastAPI()
MAX_FILES = 10
MAX_TOTAL_SIZE = 100 * 1024 * 1024  # 100MB

@app.post('/upload-multiple')
async def upload_multiple(files: list[UploadFile] = File(...)):
    if len(files) > MAX_FILES:
        raise HTTPException(400, detail=f"Maximum {MAX_FILES} files allowed")
    
    total_size = 0
    saved_files = []
    
    for file in files:
        # Stream file contents to disk
        content = b''
        while chunk := await file.read(1024 * 1024):
            content += chunk
            total_size += len(chunk)
            if total_size > MAX_TOTAL_SIZE:
                raise HTTPException(413, detail="Total upload size exceeds limit")
        
        with open(f"uploads/{file.filename}", "wb") as f:
            f.write(content)
        saved_files.append(file.filename)
    
    return {"saved_files": saved_files, "total_size": total_size}

Validating File Type Beyond Content-Type

The content_type attribute from the client is trivial to spoof. A malicious client can upload a .exe with Content-Type: image/jpeg. To validate file contents, you need to inspect file signatures (magic bytes). Use python-magic which wraps libmagic, or manually check the first few bytes. This is critical for security-sensitive uploads like profile pictures or document scans.

import magic
from fastapi import UploadFile, HTTPException

ALLOWED_MIME_TYPES = {
    'image/jpeg', 'image/png', 'application/pdf'
}

async def validate_file_type(file: UploadFile):
    # Read first 2048 bytes for magic detection
    chunk = await file.read(2048)
    await file.seek(0)  # Reset stream position
    
    mime = magic.from_buffer(chunk, mime=True)
    if mime not in ALLOWED_MIME_TYPES:
        raise HTTPException(400, detail=f"File type {mime} is not allowed. Only {ALLOWED_MIME_TYPES}")
    return True

Sanitising Filenames to Prevent Path Traversal

Saving uploaded files with the client-provided filename is dangerous. A malicious user can supply a name like ../../etc/passwd to overwrite system files or create files outside the intended directory. Always sanitize filenames: strip directory separators, use a whitelist of allowed characters, or generate a UUID-based name and store the original in a database.

import re
import uuid
from pathlib import Path

def sanitize_filename(original: str) -> str:
    # Remove directory separators and replace spaces
    safe = re.sub(r'[\\/]', '', original)
    safe = re.sub(r'[^a-zA-Z0-9._-]', '_', safe)
    # Truncate to avoid filesystem limits (255 chars typical)
    return safe[:255]

def generate_unique_filename(original: str) -> str:
    ext = Path(original).suffix
    return f"{uuid.uuid4().hex}{ext}"

# Usage:
# original = "../../etc/passwd"
# safe = sanitize_filename(original)  -> "..__etc_passwd" (after replacements)
# unique = generate_unique_filename(original) -> "a1b2c3d4..."

What Actually Is "Form Data" — And Why FastAPI Makes You Install python-multipart

Most devs slap pip install python-multipart into their requirements file without knowing why. Here's the truth: HTTP doesn't have a native "file upload" method. When a browser submits a form with a file input, it encodes the payload using multipart/form-data — a MIME-based format that splits the body into discrete parts, each with its own headers.

FastAPI doesn't ship with a multipart parser because it's a significant chunk of code that most APIs never need. python-multipart is a battle-tested C-extension-backed parser that handles boundary detection, streaming, and memory-efficient chunking. Without it, FastAPI's Form() and File() decorators throw a 422 before your handler even runs.

The key insight: every file upload is a form submission with a specific Content-Type. The form fields and files are just different parts in the same multipart envelope. FastAPI's Form() and File() are syntactic sugar that lets you access those parts without manually parsing request.body(). If you're building an API that accepts files, you're building a multipart consumer — own the stack.

// io.thecodeforge — python tutorial

// Simulating what fastapi sees under the hood
from fastapi import FastAPI, Request, File, Form, UploadFile

app = FastAPI()

@app.post("/signup")
async def signup_with_avatar(
    username: str = Form(...),
    avatar: UploadFile = File(...)
):
    # fastapi extracts these from the same multipart body
    # username comes from a text part, avatar from an octet-stream part
    return {"user": username, "file": avatar.filename}

# curl -X POST http://localhost:8000/signup \
#   -F "username=jdoe" \
#   -F "avatar=@photo.jpg"

Optional File Uploads — Because Not Every User Has a Profile Picture

Newcomers assume File(...) means mandatory. It doesn't — but the default behavior is confusing. If you set file: UploadFile = None, FastAPI will treat the missing field as an empty string, not an actual None. That's because multipart parsers emit every field present in the Content-Disposition, even when the file part has zero bytes.

The fix is to use Python's typing.Optional or a default value that the parser can recognise as "not sent". The idiomatic pattern is: file: UploadFile = File(None). This tells FastAPI: if the client doesn't send a file part, this parameter should be None, not an empty UploadFile object.

Why does this matter? If you blindly call await file.read() on a nullable upload, you'll get a RuntimeError when the file object is None. Defensive programming pays off here. Always check if file is not None before accessing any UploadFile attributes. The same pattern applies to form fields paired with optional files — mark them with Form(None) to avoid surprise 422s when clients omit them.

// io.thecodeforge — python tutorial

// Optional file with a required form field
from fastapi import FastAPI, File, Form, UploadFile
from typing import Optional

app = FastAPI()

@app.post("/profile")
async def create_profile(
    username: str = Form(...),
    avatar: Optional[UploadFile] = File(None),
    bio: Optional[str] = Form(None)
):
    # Guard before reading
    if avatar is not None:
        content = await avatar.read()
        return {"user": username, "avatar_size": len(content), "bio": bio}
    return {"user": username, "avatar_size": 0, "bio": bio}

# curl -X POST http://localhost:8000/profile \
#   -F "username=jdoe" \
#   -F "bio=DevOps engineer"

📁 Files Saved Where?

FastAPI doesn't auto-save uploaded files. The UploadFile object holds a SpooledTemporaryFile in memory or disk, but that file vanishes after the request ends unless you persist it. Why? FastAPI gives you full control over storage — cloud buckets, custom directories, or encrypted vaults. Always move the file to a permanent location using shutil.copyfileobj(). Choose a directory outside the static root to prevent direct URL access. Name collisions destroy data; prefix filenames with UUIDs or timestamps. On disk, set restrictive permissions (0o644 for files, 0o755 for directories). Never store files in /tmp — OS cleaners delete them. For cloud storage, stream directly to S3 or GCS without touching disk. If local storage is mandatory, use pathlib.Path for cross-platform safety and check available space before writes.

// io.thecodeforge — python tutorial

from fastapi import FastAPI, UploadFile, File
from pathlib import Path
import uuid
from shutil import copyfileobj

app = FastAPI()

UPLOAD_DIR = Path("uploads")
UPLOAD_DIR.mkdir(exist_ok=True)

@app.post("/upload/")
async def save_upload(file: UploadFile = File(...)):
    safe_name = f"{uuid.uuid4()}_{file.filename}"
    dest = UPLOAD_DIR / safe_name
    with dest.open("wb") as buffer:
        copyfileobj(file.file, buffer)
    return {"saved_to": str(dest)}

Facts about FastAPI

FastAPI runs on Starlette for ASGI performance and Pydantic for validation — that combination makes it one of the fastest Python web frameworks, rivaling Node.js and Go. Automatic OpenAPI docs eliminate manual API documentation. Type hints are not optional decoration; they drive request validation, serialization, and interactive docs simultaneously. FastAPI supports both sync and async handlers, letting you mix CPU-bound tasks with I/O-bound operations in the same app. Dependency injection isn't an afterthought — it's baked into every endpoint, enabling reusable logic like authentication checks or database sessions. The framework handles concurrent file uploads without blocking the main thread because UploadFile is async-native. Despite its speed, FastAPI's learning curve is shallow if you know Python type hints. Production deployments benefit from built-in CORS, gzip, and HTTPS redirect middleware.

// io.thecodeforge — python tutorial

from fastapi import FastAPI

app = FastAPI()

@app.get("/size")
def show_fastapi_size():
    # FastAPI lines of core code: ~2,500
    # Pydantic: ~10,000
    # Starlette: ~15,000
    return {
        "total_deps": 27_500,
        "your_code": "just endpoints",
        "docs_auto": True
    }

Authentication

Authentication in FastAPI is not built-in — and that's intentional. Why? You pick the scheme: OAuth2, JWT, API keys, or session cookies. FastAPI provides Depends() as the injection point. Create a reusable dependency that extracts and validates tokens before your upload handler runs. For file uploads, authenticate before accepting the file to reject unauthenticated requests early, saving bandwidth. Use OAuth2PasswordBearer for token extraction from headers, then decode JWTs with python-jose. Store secrets in environment variables, not code. For form-data uploads with authentication, send the token in the Authorization header, not inside the multipart form — multipart parsing happens after header checks. Rate-limit authenticated routes separately using middleware. Combine scopes so only authorized roles can upload sensitive files.

// io.thecodeforge — python tutorial

from fastapi import FastAPI, Depends, HTTPException, UploadFile, File
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()

async def verify_token(token: str = Depends(oauth2_scheme)):
    if token != "valid-secret":
        raise HTTPException(status_code=401, detail="Invalid token")
    return token

@app.post("/secure-upload/")
async def secure_upload(file: UploadFile = File(...),
                       token: str = Depends(verify_token)):
    return {"file": file.filename, "authenticated": True}