skip to content

In FastAPI, when should an uploaded file parameter be bytes and when UploadFile, and what does each hold in memory?

level: middleimportance: must knowfreq 45%

answer

  1. convenience versus streaming
  2. a spooled temporary file
  3. about 1 MB, then disk
  4. file.file in a def endpoint

basics

~20 s

Annotated[bytes, File()] hands the endpoint the whole file in memory, which suits small uploads. UploadFile wraps a spooled temporary file that moves to disk past about 1 MB, exposes filename and content_type, and suits large or streamed files.

solid answer

~40 s

With `Annotated[bytes, File()]` FastAPI reads the whole part and passes one `bytes` object, so memory grows with the file; that is fine for a small avatar. `UploadFile` needs no `File()` marker and wraps a `SpooledTemporaryFile`: Starlette keeps it in memory up to 1 MB and then rolls it to disk. It exposes `filename`, `content_type` and `size`, and async `read`, `seek` and `close` methods that use the thread pool once the file is on disk. In a `def` endpoint I read `file.file` directly, for example streaming a CSV through `csv.DictReader`. FastAPI closes the files after the request, and I treat `filename` and `content_type` as client-supplied hints.

code

python · 22 lines
python
import csv
import io
from typing import Annotated

from fastapi import FastAPI, File, Form, UploadFile

app = FastAPI()


@app.post("/profile/avatar")
async def update_avatar(
    display_name: Annotated[str, Form()],
    avatar: Annotated[bytes, File()],  # whole file in memory: fine for a small image
):
    return {"display_name": display_name, "avatar_bytes": len(avatar)}


@app.post("/imports/orders")
def import_orders(file: UploadFile):  # def: runs in the thread pool, may block
    text = io.TextIOWrapper(file.file, encoding="utf-8", newline="")
    rows = sum(1 for _ in csv.DictReader(text))  # streams row by row
    return {"filename": file.filename, "content_type": file.content_type, "rows": rows}

go deeper

for a junior

Recall the two declarations, that bytes needs File() while UploadFile does not, and the attributes filename and content_type.

for a middle

Explain the spooled temporary file, the roughly 1 MB rollover to disk, and why bytes keeps the whole file in memory.

for a senior

Show you would stream a large import through file.file in a def endpoint, avoid blocking reads in async def, and distrust client-supplied metadata.

for a principal

Set the team default: UploadFile for anything of unbounded size, bytes only for small fixed-purpose files, and a documented upper bound per endpoint.

FastAPI offers two ways to receive an uploaded file, and they differ in where the data lives when your code runs. Both read a file part from a `multipart/form-data` body, so both need **python-multipart** installed. ## The two declarations | | `Annotated[bytes, File()]` | `UploadFile` | |---|---|---| | Marker needed | yes, `File()`; without it `bytes` becomes a query parameter | no, the type alone marks a file part | | What the endpoint gets | one `bytes` object with the whole content | an object wrapping a spooled temporary file | | Memory | the whole file, every time | up to about 1 MB per file, the rest on disk | | Metadata | none | `filename`, `content_type`, `size`, `headers` | | Reading | already read | `await read()`, `seek()`, or `.file` | `File()` can also be added to an `UploadFile` parameter, for example `Annotated[UploadFile, File(description="CSV to import")]`, to give the docs a description. ## How `UploadFile` holds the data Before your endpoint runs, FastAPI asks Starlette to parse the whole multipart body. For each file part Starlette creates a Python `SpooledTemporaryFile`: - the file stays in memory until it grows past the spool limit, `MultiPartParser.spool_max_size`, which is 1 MB in Starlette 1.7; - past that point it **rolls over** to a real temporary file on disk, so a 2 GB upload does not need 2 GB of RAM; - `size` records how many bytes were written, and `filename` and `content_type` come from the part's own headers. The `UploadFile` methods `read(size)`, `write(data)`, `seek(offset)` and `close()` are `async`. In Starlette 1.7 they call the file directly while it is still in memory and push the call to the thread pool once the file has rolled to disk, so awaiting them does not block the event loop with disk I/O. FastAPI closes every uploaded file for you after the request has finished. ## What `bytes` costs With `Annotated[bytes, File()]` the same spooling happens first, and then FastAPI awaits `read()` on the whole part and hands you the result. The file is therefore fully in memory as one object, and so is every other `bytes` file in the same request. That is fine for a small avatar image, a signature, or a short text file where you need the content at once anyway, for example to hash it or pass it to an image library. It is the wrong choice for an import of unknown size, because memory per request then grows with the upload and a few concurrent clients can exhaust the process. ## Reading an `UploadFile` correctly Which way you read depends on the kind of endpoint: 1. In an `async def` endpoint, `await file.read()` returns everything, and `await file.read(65536)` in a loop reads in chunks. Avoid calling `file.file.read()` directly there: once the file is on disk that is a blocking call on the event loop. 2. In a `def` endpoint, which FastAPI runs in the thread pool, use `file.file`, the plain synchronous file object. It can be passed to any library that expects a file-like object, such as `csv` through `io.TextIOWrapper`, without loading the whole file. 3. After one full `read()`, call `await file.seek(0)` before reading again; a second read from the end returns `b""`. For a bulk CSV import, the `def` endpoint in the example streams rows through `csv.DictReader` while the file stays spooled on disk, so memory stays flat whatever the row count. ## Several files and what to trust - `files: list[UploadFile]` (or `Annotated[list[bytes], File()]`) collects every part sent under the same field name; the client repeats the name once per file. - `filename` and `content_type` are whatever the client wrote in the part headers. Treat them as hints: never build a storage path from `filename` without sanitising it, and check the content itself when the type matters. ## Mistakes that show up in review - `file: bytes` without `File()`: FastAPI reads it as a query parameter, and the docs page lists it among the query parameters instead of the request body. - `await file.read()` with no size on a multi-gigabyte import: the spooled file was protecting memory, and one call undoes it. - Keeping the `UploadFile`, or its `file`, in a global or a cache after the response: FastAPI closes it when the request ends, so a later read fails on a closed file. - Saving the upload to a path built from `filename`: a name such as `../../app.py` can escape the intended directory. The interview answer that lands is the trade-off in one line: `bytes` is a convenience for small files you need whole, `UploadFile` is the default for anything that can be large or that you want to stream.

  • In a FastAPI async def endpoint, what is wrong with calling file.file.read() on a large UploadFile?
    Once the spooled file has rolled to disk, `file.file.read()` is a blocking disk read on the event loop, so every other request on that worker waits for it. Use `await file.read(size)` in chunks, which Starlette runs in the thread pool for an on-disk file, or make the endpoint a plain `def` so FastAPI runs it in the thread pool and blocking reads are acceptable.
  • How does a FastAPI endpoint accept several CSV files in one request?
    Declare `files: list[UploadFile]`, or `Annotated[list[bytes], File()]` for small files. The client sends one multipart part per file under the same field name, and FastAPI collects them into the list. Each element keeps its own `filename`, `content_type` and spooled file, so large files still go to disk one by one.
  • Does a FastAPI endpoint have to close the UploadFile objects it receives?
    No. FastAPI registers the parsed form for closing and closes every uploaded file after the request has finished. You still close anything you open yourself, and you should not keep an `UploadFile` reference for work that outlives the request.

bytes is like having a delivery emptied onto your desk; UploadFile is a parcel that stays in the post room once it is too big for the desk, and you open it there.

  • UploadFile loads the whole upload into memory just like bytes does.
  • A bytes parameter without File() is still read as an uploaded file.
  • UploadFile's filename and content_type are verified by the framework.
  • await file.read() can be called inside a plain def endpoint.
  • You must close every UploadFile yourself or the temporary files leak.