urllib3

Common errors

import urllib3

http = urllib3.PoolManager(
    retries=urllib3.Retry(total=5, backoff_factor=0.5, status_forcelist=[500, 502, 503, 504]),
    timeout=urllib3.Timeout(connect=2.0, read=5.0)
)
try:
    r = http.request('GET', 'http://example.com/resource', retries=3)
    print(r.status)
except urllib3.exceptions.MaxRetryError as e:
    print(f"Request failed after max retries: {e}")

import urllib3
import certifi

http = urllib3.PoolManager(
    cert_reqs='CERT_REQUIRED',
    ca_certs=certifi.where() # Ensures the latest CA certificates are used
)
try:
    r = http.request('GET', 'https://secure.example.com')
    print(r.status)
except urllib3.exceptions.SSLError as e:
    print(f"SSL Certificate Error: {e}")

import urllib3
import socket

http = urllib3.PoolManager()
try:
    r = http.request('GET', 'http://invalid-host-or-port.com:9999') # Correct this URL
    print(r.status)
except (urllib3.exceptions.NewConnectionError, socket.gaierror) as e:
    print(f"Connection establishment failed: {e}")
    print("Please check the hostname, port, server status, and network connectivity.")

pip install urllib3

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• PoolManager

  import urllib3
  http = urllib3.PoolManager()

  Primary interface for production use; manages connection pools across multiple hosts

• urllib3.request (top-level)

  import urllib3
  resp = urllib3.request('GET', 'https://example.com')

  Convenience shortcut backed by a module-global PoolManager; side effects are shared across all callers in the same process — prefer an explicit PoolManager instance in libraries and long-running services

• VerifiedHTTPSConnection
  wrong

  from urllib3.connectionpool import VerifiedHTTPSConnection

  correct

  from urllib3.connection import VerifiedHTTPSConnection

  Importing from connectionpool was accidental in v1.x and was removed in v2.0; always import from urllib3.connection

• DEFAULT_CIPHERS
  wrong

  from urllib3.util.ssl_ import DEFAULT_CIPHERS

  correct

  # Do not import DEFAULT_CIPHERS; urllib3 2.x uses system cipher list

  DEFAULT_CIPHERS was removed in v2.0; urllib3 now delegates cipher selection to the system OpenSSL configuration

• HTTPResponse

  from urllib3.response import HTTPResponse

  Returned by PoolManager.request(); access body via resp.data (bytes) or resp.json(); use resp.stream() for chunked/streaming reads

• Retry

  from urllib3.util.retry import Retry

  Pass a Retry instance to PoolManager(retries=...) or per-request; controls retry count, backoff, status codes, and redirect behaviour

• Timeout

  from urllib3.util.timeout import Timeout

  Use Timeout(connect=2, read=5) for separate connect/read timeouts; passing a bare float sets both

Quickstart verified last tested: 2026-04-23

Create an explicit PoolManager and make GET/POST requests with timeout and retry logic.

import urllib3
from urllib3.util.retry import Retry
from urllib3.util.timeout import Timeout

# Explicit PoolManager — preferred over the module-level urllib3.request() in
# library code to avoid shared global state.
http = urllib3.PoolManager(
    timeout=Timeout(connect=3.0, read=10.0),
    retries=Retry(total=3, backoff_factor=0.5, status_forcelist=[500, 502, 503, 504]),
)

# Simple GET — response body is bytes; call .json() for JSON payloads
resp = http.request("GET", "https://httpbin.org/get")
print(resp.status)          # 200
print(resp.json())          # parsed JSON dict

# POST with form fields
resp = http.request("POST", "https://httpbin.org/post", fields={"key": "value"})
print(resp.status)

# POST with JSON body (sets Content-Type: application/json automatically)
resp = http.request("POST", "https://httpbin.org/post", json={"key": "value"})
print(resp.json()["json"])  # echoed back by httpbin

# Streaming a large response
resp = http.request("GET", "https://httpbin.org/stream-bytes/1024", preload_content=False)
for chunk in resp.stream(32):
    print(len(chunk), "bytes")
resp.release_conn()