UploadFile class

You can define path operation function parameters to be of the type UploadFile to receive files from the request.

You can import it directly from fastapi:

from fastapi import UploadFile

fastapi.UploadFile

UploadFile(file, *, size=None, filename=None, headers=None)

Bases: UploadFile

A file uploaded in a request.

Define it as a path operation function (or dependency) parameter.

If you are using a regular def function, you can use the upload_file.file attribute to access the raw standard Python file (blocking, not async), useful and needed for non-async code.

Read more about it in the FastAPI docs for Request Files.

Example

from typing import Annotated
from fastapi import FastAPI, File, UploadFile
app = FastAPI()
@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}
@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

Source code in starlette/datastructures.py

437
438
439
440
441
442
443
444
445
446
447
448

def init(
    self,
    file: typing.BinaryIO,
    *,
    size: typing.Optional[int] = None,
    filename: typing.Optional[str] = None,
    headers: “typing.Optional[Headers]” = None,
) -> None:
    self.filename = filename
    self.file = file
    self.size = size
    self.headers = headers or Headers()

file instance-attribute

file

The standard Python file object (non-async).

filename instance-attribute

filename

The original file name.

size instance-attribute

size

The size of the file in bytes.

headers instance-attribute

headers

The headers of the request.

content_type instance-attribute

content_type

The content type of the request, from the headers.

read async

read(size=-1)

Read some bytes from the file.

To be awaitable, compatible with async, this is run in threadpool.

Source code in fastapi/datastructures.py

 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111

async def read(
    self,
    size: Annotated[
        int,
        Doc(
            “””
            The number of bytes to read from the file.
            “””
        ),
    ] = -1,
) -> bytes:
    “””
    Read some bytes from the file.
    To be awaitable, compatible with async, this is run in threadpool.
    “””
    return await super().read(size)

write async

write(data)

Write some bytes to the file.

You normally wouldn’t use this from a file you read in a request.

To be awaitable, compatible with async, this is run in threadpool.

Source code in fastapi/datastructures.py

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

async def write(
    self,
    data: Annotated[
        bytes,
        Doc(
            “””
            The bytes to write to the file.
            “””
        ),
    ],
) -> None:
    “””
    Write some bytes to the file.
    You normally wouldn’t use this from a file you read in a request.
    To be awaitable, compatible with async, this is run in threadpool.
    “””
    return await super().write(data)

seek async

seek(offset)

Move to a position in the file.

Any next read or write will be done from that position.

To be awaitable, compatible with async, this is run in threadpool.

Source code in fastapi/datastructures.py

113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

async def seek(
    self,
    offset: Annotated[
        int,
        Doc(
            “””
            The position in bytes to seek to in the file.
            “””
        ),
    ],
) -> None:
    “””
    Move to a position in the file.
    Any next read or write will be done from that position.
    To be awaitable, compatible with async, this is run in threadpool.
    “””
    return await super().seek(offset)

close async

close()

Close the file.

To be awaitable, compatible with async, this is run in threadpool.

Source code in fastapi/datastructures.py

133
134
135
136
137
138
139

async def close(self) -> None:
    “””
    Close the file.
    To be awaitable, compatible with async, this is run in threadpool.
    “””
    return await super().close()