File upload is an important feature of cURL, supporting various upload methods including form uploads, binary uploads, and multi-file uploads.
Basic File Upload
Use the -F or --form parameter for form-based uploads:
# Upload single file curl -X POST https://api.example.com/upload \ -F "file=@/path/to/file.pdf" # Specify MIME type curl -X POST https://api.example.com/upload \ -F "file=@/path/to/image.png;type=image/png" # Specify filename for server curl -X POST https://api.example.com/upload \ -F "file=@/path/to/local.txt;filename=uploaded.txt"
Multiple File Upload
# Upload multiple files curl -X POST https://api.example.com/upload \ -F "file1=@/path/to/file1.pdf" \ -F "file2=@/path/to/file2.jpg" \ -F "file3=@/path/to/file3.txt" # Upload multiple files as array curl -X POST https://api.example.com/upload \ -F "files[]=@/path/to/file1.pdf" \ -F "files[]=@/path/to/file2.jpg" # Mix files and form data curl -X POST https://api.example.com/submit \ -F "name=John" \ -F "email=john@example.com" \ -F "avatar=@/path/to/avatar.jpg" \ -F "resume=@/path/to/resume.pdf"
Binary File Upload
# Use --data-binary for raw binary data curl -X POST https://api.example.com/upload \ -H "Content-Type: application/octet-stream" \ --data-binary @/path/to/file.bin # Read from stdin cat file.bin | curl -X POST https://api.example.com/upload \ -H "Content-Type: application/octet-stream" \ --data-binary @- # Upload with progress bar curl -X POST https://api.example.com/upload \ -F "file=@/path/to/large.zip" \ --progress-bar
Base64 Encoded Upload
# Encode file to Base64 before upload curl -X POST https://api.example.com/upload \ -H "Content-Type: application/json" \ -d "{\"file\":\"$(base64 -w 0 /path/to/file.pdf)\",\"filename\":\"document.pdf\"}"
Chunked Upload (Large Files)
# Upload large file with progress curl -X POST https://api.example.com/upload \ -F "file=@/path/to/large_file.zip" \ -H "Authorization: Bearer token123" \ --progress-bar | tee upload.log # Resume upload (requires server support) curl -C - -X POST https://api.example.com/upload \ -F "file=@/path/to/large_file.zip"
Upload to Cloud Storage
# AWS S3 upload curl -X PUT "https://bucket.s3.amazonaws.com/file.pdf" \ -H "Content-Type: application/pdf" \ -H "Authorization: AWS4-HMAC-SHA256 ..." \ --data-binary @/path/to/file.pdf # Upload using presigned URL curl -X PUT "https://presigned-url-here" \ -H "Content-Type: application/pdf" \ --data-binary @/path/to/file.pdf
Key Parameters
| Parameter | Purpose | Example |
|---|---|---|
-F or --form | Form upload | -F "file=@path" |
@ | Read file | @/path/to/file |
;type= | Specify MIME type | file=@img.png;type=image/png |
;filename= | Specify filename | file=@local.txt;filename=remote.txt |
--data-binary | Binary upload | --data-binary @file.bin |
-C - | Resume upload | -C - |
Complete Upload Example
# Complete upload with authentication and metadata curl -X POST https://api.example.com/v1/files/upload \ -H "Authorization: Bearer your_token" \ -H "X-Upload-Category: documents" \ -F "file=@/path/to/document.pdf" \ -F "metadata={\"title\":\"Contract\",\"tags\":[\"legal\",\"contract\"]};type=application/json" \ --progress-bar \ -o response.json # View upload result cat response.json | jq
Common Issues
# Issue 1: Incorrect file path # Solution: Use absolute path or verify relative path # Issue 2: Insufficient permissions # Solution: Check file read permissions ls -l /path/to/file # Issue 3: Upload size limit # Solution: Use chunked upload or contact server admin # Issue 4: Timeout # Solution: Increase timeout curl --max-time 600 -F "file=@large.zip" https://api.example.com/upload