httpx timeout: the 5 s default, ReadTimeout, PoolTimeout and fixes (tested)

httpx's default timeout is 5 seconds (connect, read, write and pool each). A slower endpoint raises httpx.ReadTimeout; pass timeout=30.0 (or httpx.Timeout(5.0, read=30.0)) to the request or the Client, and catch httpx.TimeoutException.

httpx has a 5-second default timeout on every request (requests has none), split into four parts: connect, read, write and pool. Measured with httpx 0.28.1 on Python 3.13.5 against a local http.server whose path is the number of seconds to wait before answering (/7 = 7 s).

1. The default: ReadTimeout after 5 seconds

import httpx, time
from srv import start
base = start()

print(httpx.Client().timeout)
t = time.monotonic()
try:
    httpx.get(base + "/7")          # server takes 7 s to answer
except httpx.TimeoutException as e:
    print(type(e).__name__, f"after {time.monotonic() - t:.1f}s:", e)
    print("TimeoutException subclass:", isinstance(e, httpx.TimeoutException))

Output:

Timeout(timeout=5.0)
ReadTimeout after 5.0s: timed out
TimeoutException subclass: True

A slow endpoint that works in a browser or with requests fails in httpx with httpx.ReadTimeout: timed out after exactly 5 seconds. All four timeout errors (ConnectTimeout, ReadTimeout, WriteTimeout, PoolTimeout) subclass httpx.TimeoutException, so catch that to handle them together.

2. Raising or disabling the timeout

import httpx, time
from srv import start
base = start()

for timeout in (10.0, None, httpx.Timeout(2.0, read=8.0)):
    t = time.monotonic()
    r = httpx.get(base + "/6", timeout=timeout)
    print(repr(timeout), "->", r.status_code, f"{time.monotonic() - t:.1f}s")

print(httpx.Timeout(10.0, connect=2.0))
try:
    httpx.Timeout(connect=2.0)
except ValueError as e:
    print("ValueError:", e)

Output:

10.0 -> 200 6.0s
None -> 200 6.0s
Timeout(connect=2.0, read=8.0, write=2.0, pool=2.0) -> 200 6.0s
Timeout(connect=2.0, read=10.0, write=10.0, pool=10.0)
ValueError: httpx.Timeout must either include a default, or set all four parameters explicitly.

Pass timeout= per request or on httpx.Client(timeout=...) / AsyncClient. A float sets all four parts; None disables the timeout entirely (the call can then hang forever, so prefer a large number); httpx.Timeout(default, read=...) sets one part and uses the default for the rest. httpx.Timeout(connect=2.0) alone is a ValueError: give a default or all four values.

3. PoolTimeout: waiting for a free connection

import httpx, threading, time
from srv import start
base = start()

client = httpx.Client(timeout=httpx.Timeout(5.0, pool=1.0),
                      limits=httpx.Limits(max_connections=1))
threading.Thread(target=client.get, args=(base + "/3",)).start()
time.sleep(0.2)
t = time.monotonic()
try:
    client.get(base + "/0")
except httpx.PoolTimeout as e:
    print(type(e).__name__, f"after {time.monotonic() - t:.1f}s", "| is TimeoutException:", isinstance(e, httpx.TimeoutException))

Output:

PoolTimeout after 1.0s | is TimeoutException: True

With Limits(max_connections=1) and one request in flight, the second request waited for a connection and raised PoolTimeout after the 1 s pool timeout. Seen under concurrency (many tasks sharing one AsyncClient), it means raise max_connections (a Client defaults to 100) or the pool timeout, not the read timeout.

4. ConnectTimeout: the host never answers

import httpx, time
t = time.monotonic()
try:
    httpx.get("http://10.255.255.1/", timeout=1.0)   # unroutable address
except httpx.TimeoutException as e:
    print(type(e).__name__, f"after {time.monotonic() - t:.1f}s")

Output:

ConnectTimeout after 1.0s

An address that drops packets gives ConnectTimeout after the connect timeout. A host that is up with nothing listening on the port fails fast with httpx.ConnectError (connection refused) instead, which is not a TimeoutException.

Related: httpx follow redirects, requests ReadTimeout, requests ConnectionError max retries.

Written with AI assistance. Measured on 2026-10-23 with httpx 0.28.1 on Python 3.13.5 against a local http.server (and an unroutable address for the connect timeout). Each block was run verbatim and the output pasted unedited. PlainHeaders is our extension; httpx is free.