Handling file uploads and multipart form data is a breeze with FastAPI. When building interactive web applications, having the ability to handle file uploads efficiently is key. You get this done in a few simple steps, from setting up necessary dependencies to creating endpoints for file uploads.
First things first, we need to set up our environment. FastAPI relies on python-multipart to parse multipart/form-data requests. It’s an essential package, so make sure to install it:
pip install python-multipart
Once that’s squared away, it’s time to set up our FastAPI application. Here’s your basic setup:
from fastapi import FastAPI, File, UploadFile, Form
from typing import Annotated
app = FastAPI()
Now, FastAPI lets you handle file uploads in two main ways: using bytes and UploadFile. Each has its benefits depending on the file size you’re dealing with.
Let’s start with bytes. This method reads the entire file into memory, making it great for small files:
@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
return {"file_size": len(file)}
However, if you need to handle larger files, UploadFile is the way to go. It allows for more efficient file streaming without loading the entire thing into memory:
@app.post("/uploadfiles/")
async def create_upload_file(file: UploadFile = File(...)):
return {"filename": file.filename}
Handling multiple file uploads? FastAPI has you covered. You can easily set up endpoints for uploading lists of files, whether as bytes or UploadFile:
@app.post("/files/")
async def create_files(files: list[bytes] = File(description="Multiple files as bytes")):
return {"file_sizes": [len(file) for file in files]}
@app.post("/uploadfiles/")
async def create_upload_files(files: list[UploadFile] = File(description="Multiple files as UploadFile")):
return {"filenames": [file.filename for file in files]}
For the front-end part, you will need an HTML form configured to handle file uploads. Setting the form’s enctype attribute to multipart/form-data is crucial. Here’s a sample form for uploading files:
@app.get("/")
async def main():
content = """
<body>
<form action="/files/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
<form action="/uploadfiles/" enctype="multipart/form-data" method="post">
<input name="files" type="file" multiple>
<input type="submit">
</form>
</body>
"""
return HTMLResponse(content=content)
Sometimes, you may want to save uploaded files on your server. This can be done efficiently with the shutil library:
import shutil
@app.post("/uploader/")
async def create_upload_file(file: UploadFile = File(...)):
with open("destination.png", "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
return {"filename": file.filename}
In some cases, you’ll need to handle form data along with file uploads. FastAPI makes this easy using Form and File annotations together. Here’s an example to guide you:
@app.post("/files/")
async def create_file(
file: Annotated[bytes, File()],
fileb: Annotated[UploadFile, File()],
token: Annotated[str, Form()],
):
return {
"file_size": len(file),
"token": token,
"fileb_content_type": fileb.content_type,
}
Handling very large files can be tricky, but it’s manageable. Streaming large file uploads is more efficient and can be achieved using libraries like streaming_form_data. Here’s a brief setup to stream and handle large files:
from fastapi import FastAPI, HTTPException
from starlette.requests import Request
from streaming_form_data import StreamingFormDataParser
from streaming_form_data.targets import FileTarget
from tempfile import NamedTemporaryFile
import os
import shutil
uploadDir = os.getcwd()
def abspath(name: str):
return os.path.join(uploadDir, os.path.basename(name))
class UploadFileTarget(FileTarget):
def __init__(self, dir: str, *args, **kwargs):
super().__init__(None, *args, **kwargs)
self.file = UploadFile(None, file=NamedTemporaryFile(delete=False, dir=dir))
self._fd = self.file.file
def on_start(self):
self.file.filename = self.filename = self.multipart_filename
if os.path.exists(abspath(self.filename)):
raise HTTPException(409, "File already exists")
app = FastAPI()
@app.post("/")
async def upload(request: Request):
parser = StreamingFormDataParser(request.headers)
target = UploadFileTarget(uploadDir)
try:
parser.register("file", target)
async for chunk in request.stream():
parser.data_received(chunk)
if target.filename:
shutil.move(target.file.file.name, abspath(target.filename))
else:
raise HTTPException(422, "Could not find file in body")
finally:
await target.file.close()
if os.path.exists(target.file.file.name):
os.unlink(target.file.file.name)
In summary, handling file uploads and multipart form data in FastAPI is straightforward and highly efficient. Using the right mix of dependencies and FastAPI’s annotations, you can create robust endpoints capable of dealing with diverse file upload scenarios. Whether handling small files or streaming large ones, FastAPI arms you with the necessary tools to ensure your application performs seamlessly. Consider your file types and sizes to select the appropriate method for managing them to keep your application snappy and reliable. These examples should set you up to handle file uploads confidently in your FastAPI projects.
