# 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 [¶](#fastapiuploadfile-)

```
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](/guides/tutorial-user-guide-request-files).

#### Example[¶](#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}
```

:::accordion{title="Source code in starlette/datastructures.py"}
```
def __init__(
    self,
    file: BinaryIO,
    *,
    size: int | None = None,
    filename: str | None = None,
    headers: Headers | None = None,
) -> None:
    self.filename = filename
    self.file = file
    self.size = size
    self.headers = headers or Headers()

    # Capture max size from SpooledTemporaryFile if one is provided. This slightly speeds up future checks.
    # Note 0 means unlimited mirroring SpooledTemporaryFile's __init__
    self._max_mem_size = getattr(self.file, "_max_size", 0)
```
:::

### file `instance-attribute` [¶](#file-instance-attribute-)

```
file
```

The standard Python file object (non-async).

### filename `instance-attribute` [¶](#filename-instance-attribute-)

```
filename
```

The original file name.

### size `instance-attribute` [¶](#size-instance-attribute-)

```
size
```

The size of the file in bytes.

### headers `instance-attribute` [¶](#headers-instance-attribute-)

```
headers
```

The headers of the request.

### content\_type `instance-attribute` [¶](#contenttype-instance-attribute-)

```
content_type
```

The content type of the request, from the headers.

### read `async` [¶](#read-async-)

```
read(size=-1)
```

Read some bytes from the file.

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

| PARAMETER | DESCRIPTION                                                                  |
| --------- | ---------------------------------------------------------------------------- |
| `size`    | The number of bytes to read from the file. **TYPE:** `int` **DEFAULT:** `-1` |

:::accordion{title="Source code in fastapi/datastructures.py"}
```
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-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.

| PARAMETER | DESCRIPTION                                       |
| --------- | ------------------------------------------------- |
| `data`    | The bytes to write to the file. **TYPE:** `bytes` |

:::accordion{title="Source code in fastapi/datastructures.py"}
```
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-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.

| PARAMETER | DESCRIPTION                                                   |
| --------- | ------------------------------------------------------------- |
| `offset`  | The position in bytes to seek to in the file. **TYPE:** `int` |

:::accordion{title="Source code in fastapi/datastructures.py"}
```
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-async-)

```
close()
```

Close the file.

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

:::accordion{title="Source code in fastapi/datastructures.py"}
```
async def close(self) -> None:
    """
    Close the file.

    To be awaitable, compatible with async, this is run in threadpool.
    """
    return await super().close()
```
:::

## Related pages

- [About](./about-index.md)
- [Advanced User Guide](./advanced-user-guide-index.md)
- [Deployment](./deployment-index.md)
- [FastAPI](./fastapi-index.md)
- [FastAPI Docs](../index.md)
- [Features](./features-index.md)
- [How To - Recipes](./how-to-recipes-index.md)
- [Learn](./learn-index.md)
- [More](./more-index.md)
- [OpenAPI](./openapi-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.