curl File Upload
Upload files with curl using multipart form data or binary transfer. Learn file upload patterns with custom filenames, MIME types, and multiple files.
Detailed Explanation
Uploading Files with curl
File uploads are a common requirement for APIs that handle images, documents, or other binary content. curl supports multiple methods for sending files to a server.
Multipart Form Upload
The most common method uses -F (form) to send files as multipart/form-data:
curl -X POST https://api.example.com/upload \
-F "file=@photo.jpg" \
-F "description=Profile photo"
The @ prefix tells curl to read the file contents from disk. Without it, curl would send the literal string "photo.jpg".
Specifying Content Type
Override the automatically detected MIME type:
curl -X POST https://api.example.com/upload \
-F "file=@data.csv;type=text/csv"
Custom Filename
Send a file with a different name than the local filename:
curl -X POST https://api.example.com/upload \
-F "file=@localfile.txt;filename=remote-name.txt"
Multiple File Uploads
Upload several files in a single request:
curl -X POST https://api.example.com/upload \
-F "files=@image1.jpg" \
-F "files=@image2.jpg" \
-F "files=@image3.jpg"
Binary Upload
For APIs that expect raw binary data instead of multipart form data, use --data-binary:
curl -X POST https://api.example.com/upload \
-H "Content-Type: application/octet-stream" \
--data-binary @largefile.zip
Streaming from stdin
Pipe data directly into curl for streaming uploads:
tar czf - ./project | curl -X POST \
-H "Content-Type: application/gzip" \
--data-binary @- https://api.example.com/upload
Progress Monitoring
Use --progress-bar for a simple progress indicator during large uploads, or -# as a shorthand. By default, curl shows a detailed transfer statistics table that includes upload speed and estimated time remaining.
Use Case
A developer building a file management system needs to upload user documents and images to a cloud storage API while preserving the original filenames and content types.