The --form option (short form: -F) in curl is used to send HTTP requests with multipart/form-data encoding. This is essential for file uploads, form submissions with mixed content types, and sending binary data to web servers.
What is multipart/form-data?
Multipart/form-data is an HTTP content type that allows sending multiple pieces of data with different content types in a single request. It's commonly used when HTML forms contain file upload fields or when you need to send both text and binary data together.
Basic Syntax
curl --form "field_name=value" URL
curl -F "field_name=value" URL
Common Use Cases
1. File Upload
Upload a single file:
curl --form "file=@document.pdf" https://httpbin.org/post
The @ symbol indicates that the value should be read from a file. The filename is automatically included in the multipart data.
2. Multiple Form Fields
Send text fields along with file uploads:
curl --form "username=john_doe" \
--form "email=john@example.com" \
--form "avatar=@profile.jpg" \
https://api.example.com/users
3. Specify Custom Filename
Override the default filename in the upload:
curl --form "document=@local-file.pdf;filename=report.pdf" \
https://api.example.com/upload
4. Set Custom Content Type
Explicitly specify the content type for uploaded files:
curl --form "data=@file.json;type=application/json" \
https://api.example.com/data
5. Send Raw Data as Form Field
Send string data directly (not from a file):
curl --form "json_data={\"key\":\"value\"};type=application/json" \
https://api.example.com/webhook
6. Multiple File Uploads
Upload multiple files in a single request:
curl --form "file1=@image1.jpg" \
--form "file2=@image2.png" \
--form "file3=@document.pdf" \
https://api.example.com/bulk-upload
Advanced Examples
Form with Headers
Add custom headers to individual form fields:
curl --form "metadata=@config.json;type=application/json;headers=\"X-Custom-Header: value\"" \
https://api.example.com/upload
Simulate HTML Form Submission
Replicate a typical web form with mixed content:
curl --form "name=John Smith" \
--form "age=30" \
--form "resume=@resume.pdf;type=application/pdf" \
--form "cover_letter=<cover_letter.txt;type=text/plain" \
https://jobs.example.com/apply
Note: < reads file content as text, while @ uploads the file as binary data.
REST API File Upload
Common pattern for REST APIs with authentication:
curl -X POST \
-H "Authorization: Bearer your_token_here" \
--form "file=@data.csv;type=text/csv" \
--form "description=Monthly sales report" \
https://api.example.com/v1/reports
Key Differences from Other Methods
| Method | Content-Type | Use Case |
|--------|-------------|----------|
| --form | multipart/form-data | File uploads, mixed content |
| --data | application/x-www-form-urlencoded | Simple form data |
| --json | application/json | JSON payloads |
Common Pitfalls
- Missing @ symbol:
curl --form "file=myfile.txt"sends the filename as text, not the file content - Incorrect field names: Ensure form field names match what the server expects
- Content type issues: Some servers are strict about content types; specify them explicitly when needed
Debugging Form Requests
To see the actual request being sent:
curl -v --form "file=@test.txt" https://httpbin.org/post
The -v flag shows the full HTTP conversation, including headers and request structure.
The --form option is powerful for integrating with web APIs, automating file uploads, and testing multipart endpoints in your development workflow.
