HTML-style form submissions
A browser or client submits ordinary fields with form encoding rather than a JSON object.
FastAPI · Function
Form
Form declares FastAPI endpoint parameters that are read from submitted form data instead of JSON or query parameters. It supports the same style of configuration as other parameter helpers, including validation and aliases.
How it works
Form marks endpoint parameters as fields from an incoming form-encoded request rather than ordinary query values or a JSON body. It derives from Body, so it accepts the same kinds of metadata and validation options, while FastAPI reads the submitted fields from the form payload.
Syntax
Form(default: Any = Undefined, *, default_factory: Callable[[], Any] | None = _Unset, media_type: str = 'application/x-www-form-urlencoded', alias: str | None = None, alias_priority: int | None = _Unset, validation_alias: str | AliasPath | AliasChoices | None = None, serialization_alias: str | None = _Unset, title: str | None = None, description: str | None = None, gt: float | None = None, ge: float | None = None, lt: float | None = None, le: float | None = None, multiple_of: float | None = None, max_digits: int | None = None, decimal_places: int | None = None, min_length: int | None = None, max_length: int | None = None, pattern: str | None = None, regex: str | None = None, discriminator: str | None = None, strict: bool | None = _Unset, multiple_of: float | None = None, allow_inf_nan: bool | None = _Unset, max_items: int | None = None, min_items: int | None = None, union_mode: Literal['smart', 'left_to_right'] = 'smart', json_schema_extra: JsonDict | None = None, **extra: Any)Parameters
| Name | Type | Description |
|---|---|---|
*args, **kwargs | Form | The form field value is declared through the annotated parameter type; Form supplies the form-body metadata and can be configured with body-parameter options such as validation, examples, and aliases. |
Returns
A parameter metadata object used by FastAPI to declare and extract a form-data input field.
Key points
- Use Form in a path-operation parameter when the client submits fields as form data.
- Form is Body-based, so it follows the framework's body-parameter declaration model.
- Useful options include validation rules, generated examples, and alternate external field names.
- FastAPI selects the form payload as the source rather than trying to decode the value from JSON.
Common mistakes
- The multipart parser dependency must be installed before handling form data.
- Annotating a parameter only with its Python type does not make it a form field; use Form explicitly.
- A request using multipart form encoding cannot simultaneously provide fields expected as JSON body data.
Example: Receive login form fields
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(
username: Annotated[str, Form()],
password: Annotated[str, Form()],
):
return {"username": username}Declares two form fields and returns the submitted username.
When to use it
Login and credential fields
An endpoint accepts credentials or other scalar fields from a multipart request.
Files plus form metadata
A request combines uploaded content with accompanying textual fields.
Interview questions
QHow do you declare a form field in FastAPI?
Use Form in the endpoint parameter declaration, for example username: Annotated[str, Form()]. FastAPI then reads that value from form data instead of interpreting it as a query parameter or JSON body field.
Follow-up: How would you receive an uploaded file and a form field together? Declare the file with File and the form value with Form; both are received as multipart form data.
QWhat capabilities does Form provide besides selecting the input source?
Form inherits directly from Body and supports the same configuration style as Body, Query, Path, and Cookie. That includes validation-related settings, examples, and aliases such as mapping a Python parameter to a hyphenated submitted name.
Follow-up: Why can an alias be useful? It lets the external form field use a name that is inconvenient or invalid as a Python identifier, while the handler uses a normal parameter name.
QWhat constraint applies when combining Form with Body or File?
The form payload uses form encoding, so it must not be combined with JSON Body fields in the same request. For requests containing files and fields, use File and Form together and send multipart form data.
Follow-up: What additional dependency is required for these requests? Install python-multipart so FastAPI can parse form submissions.
Related
BodyQueryPathCookieFile