python-requests Getting started with python-requests

30% OFF - 9th Anniversary discount on Entity Framework Extensions until December 15 with code: ZZZANNIVERSARY9


HTTP for Humans

Requests is the only Non-GMO HTTP library for Python, safe for human consumption.

Requests allows you to send organic, grass-fed HTTP/1.1 requests, without the need for manual labor. There's no need to manually add query strings to your URLs, or to form-encode your POST data. Keep-alive and HTTP connection pooling are 100% automatic, powered by urllib3, which is embedded within Requests.

The power of Requests:

>>> r = requests.get('', auth=('user', 'pass'))
>>> r.status_code
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
>>> r.text
>>> r.json()
{u'private_gists': 419, u'total_private_repos': 77, ...}

Reading the response

response = requests.get("")
text_resp = response.text

JSON response: for json-formatted responses the package provides a built-in decoder

response = requests.get('')
json_resp = response.json()

This method will raise a ValueError in case of empty response or unparseable content.

GET requests

requests.get() creates a GET request:

response = requests.get('')

Pass in query parameters as a dictionary to the params argument:

response = requests.get('', params={"a": 1, "b": 2})

For GET requests that might require basic authentication, you can include the auth paramter as follows:

response = requests.get('', auth=('user', 'pass'))

Installation or Setup

python-requests is available on PyPI, the Python Package Index, which means it can be installed through pip:

pip install requests

Up-to-date source code can be found on the requests GitHub repository

If you wish to install it from source, you can do this by either cloning the GitHub repository:

git clone git://

Or by getting the tarball (-O writes the output to file; -L follows redirects):

curl -OL

Then you can install it by executing the

python install

However you installed it, you can start using it by importing the usual way

>>> import requests
>>> requests.get('')

Other request methods

The requests module has top-level functions for most HTTP methods:

r = requests.put('', data=put_body)
r = requests.delete('')
r = requests.head('')
r = requests.options('')
r = requests.patch('', data=patch_update)

POST requests

POST requests are made with the method.

If you need to send a web form request as a POST body, pass in a dictionary with key-value pairs as the data argument; requests will encode these to a application/x-www-form-urlencoded mimetype body:

r ='', data={"a": 1, "b": 2})

If you need to POST a json payload, you can use json= . This will automatically set the Content-Type header to application/json

r ='', data={"a": 1, "b": 2})

Reading status codes

The attribute status_code contains the status code of the response

good_req = requests.get('')
code_200 = good_req.status_code

notfound_req = requests.get('')
code_404 = notfound_req.status_code will provide a list of available http status codes.

It is possible to user raise_for_status to check if the status_code was 4xx or 5xx and raise a corresponding exception in that case.

good_req = requests.get('')
# is a 200 status code so nothing happens

notfound_req = requests.get('')
# raises requests.exceptions.HTTPError: 404 Client Error

Got any python-requests Question?