Upload File Using Multipart Form Data in Curl

This article provides a quick, practical guide on how to upload files to a server using the curl command-line tool. You will learn the exact syntax for sending local files using multipart/form-data POST requests, including how to handle multiple files, custom filenames, and additional form fields in a single command.

To upload a file using multipart/form-data in curl, you use the -F (or --form) option. This option automatically forces curl to use the POST method and sets the Content-Type header to multipart/form-data.

Basic File Upload Syntax

To send a file, specify the form field name followed by =# or =@ and the path to your local file. The @ symbol tells curl to read the file from your local system.

curl -F "file=@/path/to/your/document.pdf" https://example.com/upload

In this example: * -F tells curl to send a multipart form post. * file is the name of the form field the server expects. * @/path/to/your/document.pdf is the path to the file you want to upload.

Uploading a File with Additional Form Fields

Often, APIs require you to submit metadata or other text fields alongside the file. You can do this by adding multiple -F flags to your command.

curl -F "file=@/path/to/image.png" \
     -F "username=john_doe" \
     -F "description=Profile picture upload" \
     https://example.com/upload

Uploading Multiple Files

To upload multiple files in a single request, simply use a separate -F flag for each file.

curl -F "file1=@/path/to/first_file.txt" \
     -F "file2=@/path/to/second_file.txt" \
     https://example.com/upload

Customizing the Filename and Content-Type

By default, curl extracts the filename and content-type from the file path. You can manually override these values within the -F parameter by separating them with semicolons.

curl -F "file=@/path/to/local_image.png;filename=custom_name.png;type=image/png" https://example.com/upload