Install & Compatibility
Where this runs
tested against v0.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.354s · 21.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.320s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RetryTransport
✓ from httpx_retries import RetryTransport
Retry
✓ from httpx_retries import Retry
RetryPolicy
✓ from httpx_retries import RetryPolicy
✗ from httpx_retry import RetryPolicy
A similarly named, but abandoned, package `httpx-retry` (with a hyphen) exists, which uses `RetryPolicy` but is no longer maintained. Ensure you import from `httpx_retries` (with an underscore).
This quickstart demonstrates both synchronous and asynchronous usage of `httpx-retries`. It shows how to apply the `RetryTransport` with its default retry strategy and how to configure a custom `Retry` strategy with parameters like `total` retries, `backoff_factor`, and `statuses_forcelist` to specify which HTTP status codes should trigger a retry. The example attempts to retrieve a 503 status, which will trigger the retry logic.
import httpx
from httpx_retries import RetryTransport, Retry
def sync_example():
# Basic usage with default retry strategy
with httpx.Client(transport=RetryTransport()) as client:
print("Sync Client (default retries):")
try:
response = client.get("https://httpbin.org/status/503")
print(f" Status: {response.status_code}")
except httpx.HTTPStatusError as e:
print(f" Failed after retries: {e.response.status_code}")
# Custom retry strategy
custom_retry = Retry(total=5, backoff_factor=0.5, statuses_forcelist=[503, 504])
with httpx.Client(transport=RetryTransport(retry=custom_retry)) as client:
print("\nSync Client (custom retries):")
try:
response = client.get("https://httpbin.org/status/503")
print(f" Status: {response.status_code}")
except httpx.HTTPStatusError as e:
print(f" Failed after retries: {e.response.status_code}")
async def async_example():
# Async usage with default retry strategy
async with httpx.AsyncClient(transport=RetryTransport()) as client:
print("\nAsync Client (default retries):")
try:
response = await client.get("https://httpbin.org/status/503")
print(f" Status: {response.status_code}")
except httpx.HTTPStatusError as e:
print(f" Failed after retries: {e.response.status_code}")
# Async usage with custom retry strategy
custom_retry = Retry(total=5, backoff_factor=0.5, statuses_forcelist=[503, 504])
async with httpx.AsyncClient(transport=RetryTransport(retry=custom_retry)) as client:
print("\nAsync Client (custom retries):")
try:
response = await client.get("https://httpbin.org/status/503")
print(f" Status: {response.status_code}")
except httpx.HTTPStatusError as e:
print(f" Failed after retries: {e.response.status_code}")
if __name__ == "__main__":
sync_example()
import asyncio
asyncio.run(async_example())
Debug
Known issues
gotchaHTTPX's built-in `HTTPTransport(retries=...)` only handles connection errors and timeouts, not retries based on HTTP status codes (e.g., 5xx server errors, 429 rate limits). If you need to retry requests based on specific HTTP response status codes, you must use `httpx-retries`.fixUse `httpx_retries.RetryTransport` with a configured `httpx_retries.Retry` object for status code-aware retries.
affects: All httpx versions
breakingThere is a similarly named but abandoned package `httpx-retry` (with a hyphen) on PyPI. This package is no longer maintained and explicitly advises migration. Using the wrong package can lead to unmaintained code, security vulnerabilities, or unexpected behavior.fixEnsure you are installing `httpx-retries` (with an underscore) and importing `RetryTransport` and `Retry` from `httpx_retries`.
affects: All versions, due to package name similarity.
gotchaPrior to versions 0.4.4 and 0.4.5, `RetryTransport` might not have consistently closed all responses during retry operations, potentially leading to resource leaks, especially with server errors. This was particularly relevant for connections not managed by the client's context manager.fixUpgrade to `httpx-retries` version `0.4.5` or later to ensure robust response closing during retry attempts, or explicitly manage response closing if using older versions.
affects: <0.4.5
gotchaIn versions prior to 0.3.2, if a `Retry-After` header in a response specified a time in the past, the default backoff mechanism might not have been correctly applied, potentially leading to immediate and aggressive retries. This could overload target services.fixUpdate to `httpx-retries` version `0.3.2` or later to ensure correct handling of `Retry-After` headers, even when they specify a past time, reverting to default backoff when appropriate.
affects: <0.3.2
Errors
Common errors & fixes
ImportError: cannot import name 'RetryClient' from 'httpx_retries'
The class 'RetryClient' does not exist in the 'httpx_retries' library. Retry logic is applied through a custom transport, typically 'RetryTransport'.
fixImport 'RetryTransport' and optionally 'Retry' if you need custom retry policies. Then, pass an instance of 'RetryTransport' to your HTTPX client:
```python
import httpx
from httpx_retries import RetryTransport
client = httpx.Client(transport=RetryTransport())
# For async client:
# client = httpx.AsyncClient(transport=RetryTransport())
```
httpx-retries not retrying 5xx errors
By default, 'httpx-retries' might not be configured to retry on all HTTP 5xx status codes, as its default retry conditions often prioritize connection-level issues. You need to explicitly define which status codes should trigger a retry.
fixConfigure the 'Retry' object with a 'status_forcelist' to specify which HTTP status codes should trigger a retry, then pass this 'Retry' instance to 'RetryTransport'.
```python
import httpx
from httpx_retries import Retry, RetryTransport
# Retry on 500, 502, 503, 504 status codes
retry_strategy = Retry(total=3, status_forcelist=)
transport = RetryTransport(retry=retry_strategy)
client = httpx.Client(transport=transport)
```
AttributeError: 'Client' object has no attribute 'retries'
You are attempting to set retry parameters directly on an 'httpx.Client' or 'httpx.AsyncClient' object, but 'httpx-retries' integrates retry logic by wrapping the client's transport layer, not by adding a direct attribute to the client itself.
fixInstead of setting a 'retries' attribute on the client, you must instantiate 'RetryTransport' (optionally configured with a 'Retry' object) and pass it as the 'transport' argument when creating your 'httpx.Client' or 'httpx.AsyncClient'.
```python
import httpx
from httpx_retries import RetryTransport
# Incorrect: client = httpx.Client(retries=3)
# Correct:
client = httpx.Client(transport=RetryTransport())
```
Upgrade
Version history
0.6.0latest on PyPI · released Jul 6, 2026
Audit
Dependencies
httpxrequiredCore HTTP client library for which retries are implemented. Version 0.4.1 relaxed the dependency to `>=0.20.0`.