Form

API reference for the FastAPI Form parameter function

Form

Declare a form data parameter for a path operation. Form parameters are sent as application/x-www-form-urlencoded or multipart/form-data.

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}

Signature

def Form(
    default: Any = Undefined,
    *,
    media_type: str = "application/x-www-form-urlencoded",
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | str | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
) -> Any

Parameters

default · Any · default: "Undefined"

Default value if the parameter field is not set.

media_type · str · default: "application/x-www-form-urlencoded"

The media type of this parameter field. Changing it would affect the generated OpenAPI, but currently it doesn’t affect the parsing of the data.

alias · str | None · default: "None"

An alternative name for the parameter field. This will be used to extract the data and for the generated OpenAPI.

title · str | None · default: "None"

Human-readable title for the parameter.

description · str | None · default: "None"

Human-readable description for the parameter.

gt · float | None · default: "None"

Greater than validation. If set, the value must be greater than this. Only applicable to numbers.

ge · float | None · default: "None"

Greater than or equal validation. If set, the value must be greater than or equal to this. Only applicable to numbers.

lt · float | None · default: "None"

Less than validation. If set, the value must be less than this. Only applicable to numbers.

le · float | None · default: "None"

Less than or equal validation. If set, the value must be less than or equal to this. Only applicable to numbers.

min_length · int | None · default: "None"

Minimum length for strings.

max_length · int | None · default: "None"

Maximum length for strings.

pattern · str | None · default: "None"

RegEx pattern for strings.

discriminator · str | None · default: "None"

Parameter field name for discriminating the type in a tagged union.

strict · bool | None · default: "None"

If True, strict validation is applied to the field.

multiple_of · float | None · default: "None"

Value must be a multiple of this. Only applicable to numbers.

allow_inf_nan · bool | None · default: "None"

Allow inf, -inf, nan. Only applicable to numbers.

max_digits · int | None · default: "None"

Maximum number of allowed digits for numbers.

decimal_places · int | None · default: "None"

Maximum number of decimal places allowed for numbers.

examples · list[Any] | None · default: "None"

Example values for this field.

deprecated · bool | str | None · default: "None"

Mark this parameter field as deprecated. It will affect the generated OpenAPI (visible at /docs).

include_in_schema · bool · default: "True"

Whether to include this parameter field in the generated OpenAPI.

json_schema_extra · dict[str, Any] | None · default: "None"

Any additional JSON schema data.

Examples

Basic Form

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}

To use form data, you need to install python-multipart: pip install python-multipart

Form with Validation

@app.post("/signup/")
async def signup(
    username: Annotated[str, Form(min_length=3, max_length=20)],
    email: Annotated[str, Form(pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$")],
    password: Annotated[str, Form(min_length=8)]
):
    return {"username": username, "email": email}

Optional Form Fields

@app.post("/contact/")
async def contact(
    name: Annotated[str, Form()],
    email: Annotated[str, Form()],
    phone: Annotated[str | None, Form()] = None,
    message: Annotated[str, Form()] = ""
):
    return {"name": name, "email": email, "phone": phone, "message": message}

Form with Default Values

@app.post("/subscribe/")
async def subscribe(
    email: Annotated[str, Form()],
    newsletter: Annotated[bool, Form()] = True,
    frequency: Annotated[str, Form()] = "weekly"
):
    return {"email": email, "newsletter": newsletter, "frequency": frequency}

Mixing Form and File

from fastapi import File, UploadFile

@app.post("/upload/")
async def upload(
    file: UploadFile,
    description: Annotated[str, Form()],
    public: Annotated[bool, Form()] = False
):
    return {
        "filename": file.filename,
        "description": description,
        "public": public
    }

When mixing Form() and File(), the content type automatically becomes multipart/form-data.

Common Use Cases

Login Form

@app.post("/login/")
async def login(
    username: Annotated[str, Form()],
    password: Annotated[str, Form()],
    remember_me: Annotated[bool, Form()] = False
):
    # Authenticate user
    return {"username": username, "remember_me": remember_me}

Registration Form

@app.post("/register/")
async def register(
    username: Annotated[str, Form(min_length=3, max_length=20)],
    email: Annotated[str, Form()],
    password: Annotated[str, Form(min_length=8)],
    confirm_password: Annotated[str, Form(min_length=8)],
    terms_accepted: Annotated[bool, Form()]
):
    if password != confirm_password:
        raise ValueError("Passwords do not match")
    return {"username": username, "email": email}

Search Form

@app.post("/search/")
async def search(
    query: Annotated[str, Form(min_length=1)],
    category: Annotated[str | None, Form()] = None,
    sort_by: Annotated[str, Form()] = "relevance"
):
    return {
        "query": query,
        "category": category,
        "sort_by": sort_by
    }

Contact Form

@app.post("/contact/")
async def contact(
    name: Annotated[str, Form(min_length=1)],
    email: Annotated[str, Form()],
    subject: Annotated[str, Form(min_length=1)],
    message: Annotated[str, Form(min_length=10)]
):
    # Send email
    return {"status": "Message sent"}

Form vs JSON Body

You cannot use Form() and Body() in the same path operation. They use different content types (multipart/form-data vs application/json).

Form data is sent as key-value pairs:

username=john&password=secret

JSON body is sent as JSON:

{
  "username": "john",
  "password": "secret"
}

Installation Requirement

Form data requires the python-multipart package:

pip install python-multipart