Form Data¶
When you need to receive form fields instead of JSON, you can useForm.
Info
To use forms, first installpython-multipart.
Make sure you create avirtual environment, activate it, and then install it, for example:
$pipinstallpython-multipartImportForm¶
ImportForm fromfastapi:
fromtypingimportAnnotatedfromfastapiimportFastAPI,Formapp=FastAPI()@app.post("/login/")asyncdeflogin(username:Annotated[str,Form()],password:Annotated[str,Form()]):return{"username":username}🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,Formapp=FastAPI()@app.post("/login/")asyncdeflogin(username:str=Form(),password:str=Form()):return{"username":username}DefineForm parameters¶
Create form parameters the same way you would forBody orQuery:
fromtypingimportAnnotatedfromfastapiimportFastAPI,Formapp=FastAPI()@app.post("/login/")asyncdeflogin(username:Annotated[str,Form()],password:Annotated[str,Form()]):return{"username":username}🤓 Other versions and variants
Tip
Prefer to use theAnnotated version if possible.
fromfastapiimportFastAPI,Formapp=FastAPI()@app.post("/login/")asyncdeflogin(username:str=Form(),password:str=Form()):return{"username":username}For example, in one of the ways the OAuth2 specification can be used (called "password flow") it is required to send ausername andpassword as form fields.
Thespec requires the fields to be exactly namedusername andpassword, and to be sent as form fields, not JSON.
WithForm you can declare the same configurations as withBody (andQuery,Path,Cookie), including validation, examples, an alias (e.g.user-name instead ofusername), etc.
Info
Form is a class that inherits directly fromBody.
Tip
To declare form bodies, you need to useForm explicitly, because without it the parameters would be interpreted as query parameters or body (JSON) parameters.
About "Form Fields"¶
The way HTML forms (<form></form>) sends the data to the server normally uses a "special" encoding for that data, it's different from JSON.
FastAPI will make sure to read that data from the right place instead of JSON.
Technical Details
Data from forms is normally encoded using the "media type"application/x-www-form-urlencoded.
But when the form includes files, it is encoded asmultipart/form-data. You'll read about handling files in the next chapter.
If you want to read more about these encodings and form fields, head to theMDN web docs forPOST.
Warning
You can declare multipleForm parameters in apath operation, but you can't also declareBody fields that you expect to receive as JSON, as the request will have the body encoded usingapplication/x-www-form-urlencoded instead ofapplication/json.
This is not a limitation ofFastAPI, it's part of the HTTP protocol.
Recap¶
UseForm to declare form data input parameters.