How to send a “multipart/form-data” with requests in python?

Posted on

Solving problem is about exposing yourself to as many situations as possible like How to send a “multipart/form-data” with requests in python? and practice these strategies over and over. With time, it becomes second nature and a natural way you approach any problems in general. Big or small, always start with a plan, use other strategies mentioned here till you are confident and ready to code the solution.
In this post, my aim is to share an overview the topic about How to send a “multipart/form-data” with requests in python?, which can be followed any time. Take easy to follow this discuss.

How to send a “multipart/form-data” with requests in python?

How to send a multipart/form-data with requests in python? How to send a file, I understand, but how to send the form data by this method can not understand.

Answer #1:

Basically, if you specify a files parameter (a dictionary), then requests will send a multipart/form-data POST instead of a application/x-www-form-urlencoded POST. You are not limited to using actual files in that dictionary, however:

>>> import requests
>>> response ='', files=dict(foo='bar'))
>>> response.status_code

and lets you know what headers you posted with; in response.json() we have:

>>> from pprint import pprint
>>> pprint(response.json()['headers'])
{'Accept': '*/*',
 'Accept-Encoding': 'gzip, deflate',
 'Connection': 'close',
 'Content-Length': '141',
 'Content-Type': 'multipart/form-data; '
 'Host': '',
 'User-Agent': 'python-requests/2.21.0'}

Better still, you can further control the filename, content type and additional headers for each part by using a tuple instead of a single string or bytes object. The tuple is expected to contain between 2 and 4 elements; the filename, the content, optionally a content type, and an optional dictionary of further headers.

I’d use the tuple form with None as the filename, so that the filename="..." parameter is dropped from the request for those parts:

>>> files = {'foo': 'bar'}
>>> print(requests.Request('POST', '', files=files).prepare().body.decode('utf8'))
Content-Disposition: form-data; name="foo"; filename="foo"
>>> files = {'foo': (None, 'bar')}
>>> print(requests.Request('POST', '', files=files).prepare().body.decode('utf8'))
Content-Disposition: form-data; name="foo"

files can also be a list of two-value tuples, if you need ordering and/or multiple fields with the same name:
        ('foo', (None, 'bar')),
        ('foo', (None, 'baz')),
        ('spam', (None, 'eggs')),

If you specify both files and data, then it depends on the value of data what will be used to create the POST body. If data is a string, only it willl be used; otherwise both data and files are used, with the elements in data listed first.

There is also the excellent requests-toolbelt project, which includes advanced Multipart support. It takes field definitions in the same format as the files parameter, but unlike requests, it defaults to not setting a filename parameter. In addition, it can stream the request from open file objects, where requests will first construct the request body in memory:

from requests_toolbelt.multipart.encoder import MultipartEncoder
mp_encoder = MultipartEncoder(
        'foo': 'bar',
        # plain file object, no filename or mime type produces a
        # Content-Disposition header with just the part name
        'spam': ('spam.txt', open('spam.txt', 'rb'), 'text/plain'),
r =
    data=mp_encoder,  # The MultipartEncoder is posted as data, don't use files=...!
    # The MultipartEncoder provides the content-type header with the boundary:
    headers={'Content-Type': mp_encoder.content_type}

Fields follow the same conventions; use a tuple with between 2 and 4 elements to add a filename, part mime-type or extra headers. Unlike the files parameter, no attempt is made to find a default filename value if you don’t use a tuple.

Answered By: Martijn Pieters

Answer #2:

Since the previous answers were written, requests have changed. Have a look at the bug thread at Github for more detail and this comment for an example.

In short, the files parameter takes a dict with the key being the name of the form field and the value being either a string or a 2, 3 or 4-length tuple, as described in the section POST a Multipart-Encoded File in the requests quickstart:

>>> url = ''
>>> files = {'file': ('report.xls', open('report.xls', 'rb'), 'application/', {'Expires': '0'})}

In the above, the tuple is composed as follows:

(filename, data, content_type, headers)

If the value is just a string, the filename will be the same as the key, as in the following:

>>> files = {'obvius_session_id': '72c2b6f406cdabd578c5fd7598557c52'}
Content-Disposition: form-data; name="obvius_session_id"; filename="obvius_session_id"
Content-Type: application/octet-stream

If the value is a tuple and the first entry is None the filename property will not be included:

>>> files = {'obvius_session_id': (None, '72c2b6f406cdabd578c5fd7598557c52')}
Content-Disposition: form-data; name="obvius_session_id"
Content-Type: application/octet-stream
Answered By: runejuhl

Answer #3:

You need to use the files parameter to send a multipart form POST request even when you do not need to upload any files.

From the original requests source:

def request(method, url, **kwargs):
    """Constructs and sends a :class:`Request <Request>`.
    :param files: (optional) Dictionary of ``'name': file-like-objects``
        (or ``{'name': file-tuple}``) for multipart encoding upload.
        ``file-tuple`` can be a 2-tuple ``('filename', fileobj)``,
        3-tuple ``('filename', fileobj, 'content_type')``
        or a 4-tuple ``('filename', fileobj, 'content_type', custom_headers)``,
        where ``'content-type'`` is a string
        defining the content type of the given file
        and ``custom_headers`` a dict-like object
        containing additional headers to add for the file.

The relevant part is: file-tuple can be a2-tuple, 3-tupleor a4-tuple.

Based on the above, the simplest multipart form request that includes both files to upload and form fields will look like this:

multipart_form_data = {
    'file2': ('', open('', 'rb')),
    'action': (None, 'store'),
    'path': (None, '/path1')
response ='', files=multipart_form_data)

? Note the None as the first argument in the tuple for plain text fields — this is a placeholder for the filename field which is only used for file uploads, but for text fields passing None as the first parameter is required in order for the data to be submitted.

Multiple fields with the same name

If you need to post multiple fields with the same name then instead of a dictionary you can define your payload as a list (or a tuple) of tuples:

multipart_form_data = (
    ('file2', ('', open('', 'rb'))),
    ('action', (None, 'store')),
    ('path', (None, '/path1')),
    ('path', (None, '/path2')),
    ('path', (None, '/path3')),

Streaming requests API

If the above API is not pythonic enough for you, then consider using requests toolbelt (pip install requests_toolbelt) which is an extension of the core requests module that provides support for file upload streaming as well as the MultipartEncoder which can be used instead of files, and which also lets you define the payload as a dictionary, tuple or list.

MultipartEncoder can be used both for multipart requests with or without actual upload fields. It must be assigned to the data parameter.

import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
multipart_data = MultipartEncoder(
            # a file upload field
            'file': ('', open('', 'rb'), 'text/plain')
            # plain text fields
            'field0': 'value0',
            'field1': 'value1',
response ='', data=multipart_data,
                  headers={'Content-Type': multipart_data.content_type})

If you need to send multiple fields with the same name, or if the order of form fields is important, then a tuple or a list can be used instead of a dictionary:

multipart_data = MultipartEncoder(
            ('action', 'ingest'),
            ('item', 'spam'),
            ('item', 'sausage'),
            ('item', 'eggs'),
Answered By: ccpizza

Answer #4:

Here is the simple code snippet to upload a single file with additional parameters using requests:

url = 'https://<file_upload_url>'
fp = '/Users/jainik/Desktop/data.csv'
files = {'file': open(fp, 'rb')}
payload = {'file_id': '1234'}
response = requests.put(url, files=files, data=payload, verify=False)

Please note that you don’t need to explicitly specify any content type.

NOTE: Wanted to comment on one of the above answers but could not because of low reputation so drafted a new response here.

Answered By: Jainik

Answer #5:

You need to use the name attribute of the upload file that is in the HTML of the site. Example:

autocomplete="off" name="image">

You see name="image">? You can find it in the HTML of a site for uploading the file. You need to use it to upload the file with Multipart/form-data


import requests
site = '' # the site where you upload the file
filename = 'image.jpg'  # name example

Here, in the place of image, add the name of the upload file in HTML

up = {'image':(filename, open(filename, 'rb'), "multipart/form-data")}

If the upload requires to click the button for upload, you can use like that:

data = {
     "Button" : "Submit",

Then start the request

request =, files=up, data=data)

And done, file uploaded succesfully

Answered By: Skiller Dz

Answer #6:

Send multipart/form-data key and value

curl command:

curl -X PUT ...
-H 'content-type: multipart/form-data; boundary=----xxx'
-F taskStatus=1

python requests – More complicated POST requests:

    updateTaskUrl = ""
    updateInfoDict = {
        "taskStatus": 1,
    resp = requests.put(updateTaskUrl, data=updateInfoDict)

Send multipart/form-data file

curl command:

curl -X POST ...
-H 'content-type: multipart/form-data; boundary=----xxx'
-F file=@/Users/xxx.txt

python requests – POST a Multipart-Encoded File:

    filePath = "/Users/xxx.txt"
    fileFp = open(filePath, 'rb')
    fileInfoDict = {
        "file": fileFp,
    resp =, files=fileInfoDict)

that’s all.

Answered By: crifan

Answer #7:

To clarify examples given above,

“You need to use the files parameter to send a multipart form POST request even when you do not need to upload any files.”


won’t work, unfortunately.

You will need to put some dummy values in, e.g.

files={"foo": "bar"}

I came up against this when trying to upload files to Bitbucket’s REST API and had to write this abomination to avoid the dreaded “Unsupported Media Type” error:

url = ""
payload = {'branch': 'master',
           'content': 'text that will appear in my file',
           'message': 'uploading directly from python'}
files = {"foo": "bar"}
response = requests.put(url, data=payload, files=files)


Answered By: RCross

Answer #8:

import requests
# assume sending two files
url = "put ur url here"
f1 = open("file 1 path", 'rb')
f2 = open("file 2 path", 'rb')
response =,files={"file1 name": f1, "file2 name":f2})
Answered By: Mohamed Mos?d

Leave a Reply

Your email address will not be published.