554

I would like to use cURL to not only send data parameters in HTTP POST but to also upload files with specific form name. How should I go about doing that ?

HTTP Post parameters:

userid = 12345 filecomment = This is an image file

HTTP File upload: File location = /home/user1/Desktop/test.jpg Form name for file = image (correspond to the $_FILES['image'] at the PHP side)

I figured part of the cURL command as follows:

curl -d "userid=1&filecomment=This is an image file" --data-binary @"/home/user1/Desktop/test.jpg" localhost/uploader.php

The problem I am getting is as follows:

Notice: Undefined index: image in /var/www/uploader.php

The problem is I am using $_FILES['image'] to pick up files in the PHP script.

How do I adjust my cURL commands accordingly ?

0

11 Answers 11

820

You need to use the -F option:
-F/--form <name=content> Specify HTTP multipart POST data (H)

Try this:

curl \
  -F "userid=1" \
  -F "filecomment=This is an image file" \
  -F "image=@/home/user1/Desktop/test.jpg" \
  localhost/uploader.php
11
  • 1
    I'm confused by the part about url-encoding the file. I have uploaded JPG and PNG files like this without modifying them, without any problems. May 16, 2013 at 0:27
  • 1
    @DavidGelbart You're right. My initial answer referenced the -d option by mistake, which needs the input URL-encoded. I should have removed that when I updated the answer to the -F option. Thanks for catching that.
    – jimp
    Jun 25, 2013 at 19:06
  • 3
    @user956424 In the example, set "image" to the name of your field. And some languages, such as PHP, will build an array if you specify something like "image[]" for the inputs that need to be grouped together.
    – jimp
    Nov 11, 2016 at 20:48
  • 11
    What is the @ in image=@/..?
    – Timo
    Jul 16, 2018 at 15:51
  • 16
    @Timo It means the content for the named form field should be loaded from a file path. Without it the string argument itself is passed through.
    – jimp
    Jul 18, 2018 at 4:55
146

Catching the user id as path variable (recommended):

curl -i -X POST -H "Content-Type: multipart/form-data" 
-F "[email protected]" http://mysuperserver/media/1234/upload/

Catching the user id as part of the form:

curl -i -X POST -H "Content-Type: multipart/form-data" 
-F "[email protected];userid=1234" http://mysuperserver/media/upload/

or:

curl -i -X POST -H "Content-Type: multipart/form-data" 
-F "data[email protected]" -F "userid=1234" http://mysuperserver/media/upload/
2
  • 26
    use -F needn't set "Content-Type: multipart/form-data"
    – William Hu
    Jan 15, 2016 at 2:26
  • 14
    I couldn't get -F to work properly with that semicolon separator you indicated. Instead, I had to provide two redundant -F arguments. Like: -F "[email protected]" -F "userid=1234" Oct 23, 2016 at 17:38
25

if you are uploading binary file such as csv, use below format to upload file

curl -X POST \
    'http://localhost:8080/workers' \
    -H 'authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyIsInR5cGUiOiJhY2Nlc3MifQ.eyJ1c2VySWQiOjEsImFjY291bnRJZCI6MSwiaWF0IjoxNTExMzMwMzg5LCJleHAiOjE1MTM5MjIzODksImF1ZCI6Imh0dHBzOi8veW91cmRvbWFpbi5jb20iLCJpc3MiOiJmZWF0aGVycyIsInN1YiI6ImFub255bW91cyJ9.HWk7qJ0uK6SEi8qSeeB6-TGslDlZOTpG51U6kVi8nYc' \
    -H 'content-type: application/x-www-form-urlencoded' \
    --data-binary '@/home/limitless/Downloads/iRoute Masters - Workers.csv'
6
  • 14
    I would like to see an example of a binary csv file.
    – polis
    Jan 11, 2019 at 6:33
  • 11
    @polis the option --data-binary instructs curl to not do any pre-processing of the data, as opposed to --data flag. to address your comment directly, note that text is also binary, but we can interpret it as ASCII characters. If you really want a distinct example, think about a CSV whose fields contain emoji. Their bytes do not directly map to text May 9, 2019 at 11:52
  • 4
    if anyone is googling: --data-binary works on AzureBlob direct upload url learn.microsoft.com/en-us/rest/api/storageservices/… Jul 14, 2020 at 6:43
  • 2
    All data in a (typical) computer is binary. ASCII and UTF-8 are binary encodings for text data Feb 15, 2022 at 20:40
  • @polis What is a binary csv file? Dec 5, 2022 at 9:18
24

Here is my solution, I have been reading a lot of posts and they were really helpful. Finally I wrote some code for small files, with cURL and PHP that I think its really useful.

public function postFile()
{    
        $file_url = "test.txt";  //here is the file route, in this case is on same directory but you can set URL too like "http://examplewebsite.com/test.txt"
        $eol = "\r\n"; //default line-break for mime type
        $BOUNDARY = md5(time()); //random boundaryid, is a separator for each param on my post curl function
        $BODY=""; //init my curl body
        $BODY.= '--'.$BOUNDARY. $eol; //start param header
        $BODY .= 'Content-Disposition: form-data; name="sometext"' . $eol . $eol; // last Content with 2 $eol, in this case is only 1 content.
        $BODY .= "Some Data" . $eol;//param data in this case is a simple post data and 1 $eol for the end of the data
        $BODY.= '--'.$BOUNDARY. $eol; // start 2nd param,
        $BODY.= 'Content-Disposition: form-data; name="somefile"; filename="test.txt"'. $eol ; //first Content data for post file, remember you only put 1 when you are going to add more Contents, and 2 on the last, to close the Content Instance
        $BODY.= 'Content-Type: application/octet-stream' . $eol; //Same before row
        $BODY.= 'Content-Transfer-Encoding: base64' . $eol . $eol; // we put the last Content and 2 $eol,
        $BODY.= chunk_split(base64_encode(file_get_contents($file_url))) . $eol; // we write the Base64 File Content and the $eol to finish the data,
        $BODY.= '--'.$BOUNDARY .'--' . $eol. $eol; // we close the param and the post width "--" and 2 $eol at the end of our boundary header.



        $ch = curl_init(); //init curl
        curl_setopt($ch, CURLOPT_HTTPHEADER, array(
                         'X_PARAM_TOKEN : 71e2cb8b-42b7-4bf0-b2e8-53fbd2f578f9' //custom header for my api validation you can get it from $_SERVER["HTTP_X_PARAM_TOKEN"] variable
                         ,"Content-Type: multipart/form-data; boundary=".$BOUNDARY) //setting our mime type for make it work on $_FILE variable
                    );
        curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/1.0 (Windows NT 6.1; WOW64; rv:28.0) Gecko/20100101 Firefox/28.0'); //setting our user agent
        curl_setopt($ch, CURLOPT_URL, "api.endpoint.post"); //setting our api post url
        curl_setopt($ch, CURLOPT_COOKIEJAR, $BOUNDARY.'.txt'); //saving cookies just in case we want
        curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1); // call return content
        curl_setopt ($ch, CURLOPT_FOLLOWLOCATION, 1); navigate the endpoint
        curl_setopt($ch, CURLOPT_POST, true); //set as post
        curl_setopt($ch, CURLOPT_POSTFIELDS, $BODY); // set our $BODY 


        $response = curl_exec($ch); // start curl navigation

     print_r($response); //print response

}

With this we should be get on the "api.endpoint.post" the following vars posted. You can easily test with this script, and you should be receive this debugs on the function postFile() at the last row.

print_r($response); //print response

public function getPostFile()
{

    echo "\n\n_SERVER\n";
    echo "<pre>";
    print_r($_SERVER['HTTP_X_PARAM_TOKEN']);
    echo "/<pre>";
    echo "_POST\n";
    echo "<pre>";
    print_r($_POST['sometext']);
    echo "/<pre>";
    echo "_FILES\n";
    echo "<pre>";
    print_r($_FILEST['somefile']);
    echo "/<pre>";
}

It should work well, they may be better solutions but this works and is really helpful to understand how the Boundary and multipart/from-data mime works on PHP and cURL library.

1
  • if you need to send not-encoded file change this lines $BODY.= 'Content-Transfer-Encoding: multipart/form-data' . $eol . $eol; // we put the last Content and 2 $eol, $BODY.= file_get_contents($file_url) . $eol; // we write the Base64 File Content and the $eol to finish the data,
    – icy
    Apr 13, 2015 at 8:24
13

After a lot of tries this command worked for me:

curl -v -F filename=image.jpg -F [email protected] http://localhost:8080/api/upload
8

The issue that lead me here turned out to be a basic user error - I wasn't including the @ sign in the path of the file and so curl was posting the path/name of the file rather than the contents. The Content-Length value was therefore 8 rather than the 479 I expected to see given the legnth of my test file.

The Content-Length header will be automatically calculated when curl reads and posts the file.

curl -i -H "Content-Type: application/xml" --data "@test.xml" -v -X POST https://<url>/<uri/

... < Content-Length: 479 ...

Posting this here to assist other newbies in future.

5

As an alternative to curl, you can use HTTPie, it'a CLI, cURL-like tool for humans.

  1. Installation instructions: https://github.com/jakubroztocil/httpie#installation

  2. Then, run:

    http -f POST http://localhost:4040/api/users username=johnsnow photo@images/avatar.jpg
    
    HTTP/1.1 200 OK
    Access-Control-Expose-Headers: X-Frontend
    Cache-control: no-store
    Connection: keep-alive
    Content-Encoding: gzip
    Content-Length: 89
    Content-Type: text/html; charset=windows-1251
    Date: Tue, 26 Jun 2018 11:11:55 GMT
    Pragma: no-cache
    Server: Apache
    Vary: Accept-Encoding
    X-Frontend: front623311
    
    ...
    
4
cat test.txt 

file test.txt content.

curl -v -F "hello=word" -F "[email protected]" https://httpbin.org/post

> POST /post HTTP/2
> Host: httpbin.org
> user-agent: curl/7.68.0
> accept: */*
> content-length: 307
> content-type: multipart/form-data; boundary=------------------------78a9f655d8c87a53
> 
* Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
* We are completely uploaded and fine
< HTTP/2 200 
< date: Mon, 15 Nov 2021 06:18:47 GMT
< content-type: application/json
< content-length: 510
< server: gunicorn/19.9.0
< access-control-allow-origin: *
< access-control-allow-credentials: true
< 
{
  "args": {}, 
  "data": "", 
  "files": {
    "file": "file test.txt content.\n"
  }, 
  "form": {
    "hello": "word"
  }, 
  "headers": {
    "Accept": "*/*", 
    "Content-Length": "307", 
    "Content-Type": "multipart/form-data; boundary=------------------------78a9f655d8c87a53", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.68.0", 
    "X-Amzn-Trace-Id": "Root=1-6191fbc7-6c68fead194d943d07148860"
  }, 
  "json": null, 
  "origin": "43.129.xx.xxx", 
  "url": "https://httpbin.org/post"
}
1
  • From the entire page of answers, this is the only answer that works for me. -F "[email protected]". On the backend, FastAPI expects a request.filename property in the request object, I still need to use file=@... in the curl request (because that is usually expected by the standard endpoint FastAPI function). May 23, 2022 at 0:23
3

I got it worked with this command curl -F 'filename=@/home/yourhomedirextory/file.txt' http://yourserver/upload

2

Here is how to correctly escape arbitrary filenames of uploaded files with bash:

#!/bin/bash
set -eu

f="$1"
f=${f//\\/\\\\}
f=${f//\"/\\\"}
f=${f//;/\\;}

curl --silent --form "uploaded=@\"$f\"" "$2"
2

save all sent files to folder: php file on host. u.php:

<?php
$uploaddir = 'C:/VALID_DIR/';
 echo '<pre>';
foreach ($_FILES as $key => $file) {
    if(!isset($file) || !isset($file['name'])) continue;
    $uploadfile = $uploaddir . basename($file['name']);
   
    if (move_uploaded_file($file['tmp_name'], $uploadfile)) {
        echo "$key file > $uploadfile .\n";
    } else {
        echo " Error $key  file.\n";
    }
}
print_r($_FILES);
print "</pre>";?>

Usage from client:

curl -v -F filename=ff.xml -F [email protected] https://myhost.com/u.php

This is worked for me.

My VM crashed it has only internet connection. I recovered some files this way.

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.