Skip to content

Requests

The HTTP client that made Python's networking approachable — synchronous, readable, everywhere.

Web & HTTPWebPython
Official docs ↗GitHub ↗

What it is

Requests is an elegant and simple HTTP library for Python, designed to make sending HTTP/1.1 requests easy and human-friendly. It abstracts the complexities of handling HTTP connections, cookies, headers, and authentication.

Requests allows you to send HTTP/1.1 requests using methods such as GET, POST, PUT, DELETE, HEAD, and OPTIONS. You can pass parameters, headers, JSON payloads, handle cookies, manage sessions, and handle authentication easily.

Maturity
Extremely stable — the API has barely changed in a decade
Licence
Apache 2.0
Watch for
Always pass a `timeout`; Requests waits forever by default

When to use it

The question documentation cannot answer for you — because it cannot recommend something else.

Reach for it when

  • Any synchronous script, CLI tool or background job that calls an HTTP API
  • You want the shortest possible distance between an idea and a working API call
  • The codebase is not async, and adding an event loop would be more trouble than it is worth

Look elsewhere when

  • Your application is built on asyncio — Requests blocks the event loop, so use httpx or aiohttp
  • You need HTTP/2 or connection-level control that Requests does not expose

Installation

pip install requests

Getting started

The smallest useful thing you can do with it, and what each part means.

Simple GET request
import requests
response = requests.get('https://httpbin.org/get')
print(response.status_code)
print(response.json())
This example performs a GET request to a URL and prints the HTTP status code and JSON response.
POST request with JSON payload
import requests
payload = {'key':'value'}
response = requests.post('https://httpbin.org/post', json=payload)
print(response.json())
Sends a POST request with a JSON payload to the specified URL.

Advanced usage

Where the library earns its place over a simpler alternative.

Session handling
import requests
session = requests.Session()
session.get('https://httpbin.org/cookies/set/sessioncookie/123456789')
response = session.get('https://httpbin.org/cookies')
print(response.text)
Uses a Session object to persist cookies and headers across multiple requests.
Custom headers
import requests
headers = {'User-Agent': 'my-app/0.0.1'}
response = requests.get('https://httpbin.org/headers', headers=headers)
print(response.json())
Shows how to send custom HTTP headers with a request.
Timeouts and retries
import requests
try:
    response = requests.get('https://httpbin.org/delay/10', timeout=5)
except requests.exceptions.Timeout:
    print('Request timed out')
Demonstrates handling of request timeouts.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

requests.exceptions.Timeout
Use the timeout parameter in requests.get/post to prevent indefinite waiting.
requests.exceptions.ConnectionError
Check network connectivity or use retry mechanisms for robustness.
requests.exceptions.HTTPError
Call response.raise_for_status() to catch HTTP errors like 4xx or 5xx.

Alternatives

Comparable options, and the reason you would pick one over the other.

Background

Why it exists, and what it was reacting to.

Requests was created by Kenneth Reitz in 2011 to simplify HTTP requests in Python. Its goal was to provide a more readable and intuitive API compared to urllib and urllib2. Over the years, it became one of the most widely used Python libraries for web interactions, API clients, and automation tasks.

Related libraries

Others in Web & HTTP for Python.

← All Python librariesPython guide