request-files

20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Install python-multipart for file uploads

To receive uploaded files in FastAPI, you must first install the python-multipart package. Use the command `uv add python-multipart`. This is required because uploaded files are sent as form data.

Import File and UploadFile from fastapi

To work with file uploads, import File and UploadFile directly from the fastapi module.

File is a class that inherits from Form

File is a class that inherits directly from Form. When imported from FastAPI, Query, Path, File and similar are actually functions that return special classes.

Declare file parameters like Body or Form parameters

File parameters are declared the same way as Body or Form parameters. You must use the File class to declare File bodies, because otherwise parameters would be interpreted as query or JSON body parameters.

Read files as bytes in FastAPI

If you declare a path operation function parameter with type bytes, FastAPI will read the file and you will receive the contents as bytes. The entire file contents are stored in memory, which works well for small files but not for large files.

UploadFile attributes

UploadFile has three main attributes: filename (a str with the original file name, e.g. myimage.jpg), content_type (a str with the MIME type/media type, e.g. image/jpeg), and file (a SpooledTemporaryFile object that is a file-like object you can pass to other libraries).

UploadFile async methods

UploadFile provides the following async methods that must be awaited: write(data) writes str or bytes to the file, read(size) reads size bytes/characters from the file, seek(offset) moves to a byte position in the file (e.g. await myfile.seek(0) goes to the start), and close() closes the file.

UploadFile spooled file advantages over bytes

UploadFile uses a spooled file stored in memory up to a maximum size limit, then on disk beyond that limit. This means UploadFile works well for large files like images, videos, and large binaries without consuming all memory. You don't have to use File() in the default value when using UploadFile. UploadFile has a file-like async interface and exposes a SpooledTemporaryFile object you can pass to other libraries.

Read UploadFile in async vs sync path operations

In an async path operation function, get UploadFile contents with await: contents = await myfile.read(). In a normal def path operation function, access the UploadFile.file attribute directly: contents = myfile.file.read().

FastAPI runs async file methods in threadpool

When using async methods on UploadFile, FastAPI runs the file methods in a threadpool and awaits them.

Form data encoding for files vs non-files

Data from forms without files is encoded using the media type application/x-www-form-urlencoded. When a form includes files, it is encoded as multipart/form-data. FastAPI detects File declarations and reads from the correct part of the body.

Make file uploads optional

You can make a file optional by using standard type annotations and setting a default value of None.

Upload multiple files

To upload multiple files, declare a list of bytes or UploadFile. Multiple files are associated to the same form field sent using form data. You will receive a list of bytes or UploadFiles as declared.

Multiple file uploads with File() metadata

You can use File() to set additional parameters for multiple file uploads, including with UploadFile.

python-multipart dependency for file uploads

To receive uploaded files and form data, you must first install the python-multipart package. Install it using: uv add python-multipart

Import File and Form from fastapi

File and Form are imported from fastapi to define file and form parameters in path operations.

Declare File and Form parameters

File and Form parameters are declared the same way as Body or Query parameters in path operations. The files and form fields are uploaded as form data using multipart/form-data encoding.

Mixed file and form parameter types

You can declare some file parameters as bytes and others as UploadFile in the same path operation.

Cannot combine File/Form with JSON Body parameters

You cannot declare both File or Form parameters and Body fields that expect JSON in the same path operation. When File or Form parameters are present, the request body is encoded as multipart/form-data instead of application/json. This is an HTTP protocol requirement, not a FastAPI limitation.

Use case for File and Form together

Use File and Form together in the same request when you need to receive both data and files simultaneously.

Give your agent this brain