Python FastAPI Tutorial (Part 12): File Uploads - Image Processing, Validation, and Storage

Process images with Pillow

Resize uploads to 300x300 pixels using LANCZOS resampling, convert to RGB format to handle transparency, fix EXIF orientation issues, and save as optimized JPEG with quality set to 85.

Handle CPU-bound work in async contexts

Offload image processing to separate threads using Starlette's run_in_threadpool to prevent blocking the async event loop during computationally intensive Pillow operations.

Generate secure unique filenames

Create UUID4 filenames instead of using client-provided names to prevent file collisions, directory traversal attacks, and security issues from malicious file names.

Validate actual file content

Verify uploaded files are valid images by attempting to open them with Pillow and catching UnidentifiedImageError rather than trusting client-provided Content-Type headers.

Enforce upload size limits

Configure a maximum file size setting (default 5MB) and validate content length after reading to protect the server from excessive memory consumption and denial-of-service attacks.

Secure API schemas

Remove image_file fields from Pydantic update schemas to prevent users from manipulating file paths directly through JSON endpoints, restricting changes to dedicated upload endpoints only.

Maintain safe transaction ordering

Save new image files to disk before updating the database, and only delete old files after successful database commits to prevent losing user profile pictures if transactions fail.

Use dedicated upload endpoints

Create separate PATCH endpoints using UploadFile for multipart/form-data rather than mixing binary file data with JSON payloads, keeping concerns clean and manageable.

Implement proper cleanup

Delete physical profile picture files when users upload replacements or delete their accounts, but only after confirming database updates succeed to avoid orphaned files or broken references.