Need help with unirest-python?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

431 Stars 113 Forks MIT License 149 Commits 21 Opened issues


Unirest in Python: Simplified, lightweight HTTP client library.

Services available


Need anything else?

Contributors list

Unirest for Python Build Status version

License Downloads Dependencies Gitter

Unirest is a set of lightweight HTTP libraries available in multiple languages, built and maintained by Mashape, who also maintain the open-source API Gateway Kong.


  • Make
  • Both syncronous and asynchronous (non-blocking) requests
  • Supports form parameters, file uploads and custom body entities
  • Supports gzip
  • Supports Basic Authentication natively
  • Customizable timeout
  • Customizable default headers for every request (DRY)
  • Automatic JSON parsing into a native object for JSON responses


To utilize Unirest, install it using pip:

$ pip install unirest

After installing the pip package, you can now begin simplifying requests by importing unirest:

import unirest

Creating Requests

So you're probably wondering how using Unirest makes creating requests in Python easier, let's start with a working example:

response ="", headers={ "Accept": "application/json" }, params={ "parameter": 23, "foo": "bar" })

response.code # The HTTP status code response.headers # The HTTP headers response.body # The parsed response response.raw_body # The unparsed response

Asynchronous Requests

Python also supports asynchronous requests in which you can define a

function to be passed along and invoked when Unirest receives the response:
def callback_function(response):
  response.code # The HTTP status code
  response.headers # The HTTP headers
  response.body # The parsed response
  response.raw_body # The unparsed response

thread ="", headers={ "Accept": "application/json" }, params={ "parameter": 23, "foo": "bar" }, callback=callback_function)

File Uploads

Transferring file data requires that you

the file in a readable
response ="", headers={"Accept": "application/json"},
    "parameter": "value",
    "file": open("/tmp/file", mode="r")

Custom Entity Body

import json

response ="", headers={ "Accept": "application/json" }, params=json.dumps({ "parameter": "value", "foo": "bar" }) )

Note: For the sake of semplicity, even with custom entities in the body, the keyword argument is still

(instead of
for example). I'm looking for feedback on this.

Basic Authentication

Authenticating the request with basic authentication can be done by providing an

array like:
response = unirest.get("", auth=('username', 'password'))


unirest.get(url, headers = {}, params = {}, auth = (), callback = None), headers = {}, params = {}, auth = (), callback = None)
unirest.put(url, headers = {}, params = {}, auth = (), callback = None)
unirest.patch(url, headers = {}, params = {}, auth = (), callback = None)    
unirest.delete(url, headers = {}, params = {}, auth = (), callback = None)
  • url
    - Endpoint, address, or URI to be acted upon and requested information from in a string format.
  • headers
    - Request Headers as an associative array
  • params
    - Request Body as an associative array or object
  • auth
    - The Basic Authentication credentials as an array
  • callback
    - Asychronous callback method to be invoked upon result.


Upon receiving a response, Unirest returns the result in the form of an Object. This object should always have the same keys for each language regarding to the response details.

  • code
    - HTTP Response Status Code (Example 200)
  • headers
    - HTTP Response Headers
  • body
    - Parsed response body where applicable, for example JSON responses are parsed to Objects / Associative Arrays.
  • raw_body
    - Un-parsed response body

Advanced Configuration

You can set some advanced configuration to tune Unirest-Python:


You can set a custom timeout value (in seconds):

unirest.timeout(5) # 5s timeout

Default Request Headers

You can set default headers that will be sent on every request:


You can clear the default headers anytime with:


Made with ♥ from the Mashape team

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.