HTTPX2: The Next-Gen Python HTTP Client

HTTPX2 is a modern, powerful HTTP client for Python designed to provide a robust path forward for developers. It supports both HTTP/1.1 and HTTP/2, offering a flexible choice between synchronous and asynchronous APIs.

A Note on Heritage: HTTPX2 is a direct continuation of the incredible work pioneered by @lovelydinosaur and the wider HTTPX community. We are deeply indebted to them for creating a foundational tool for the Python ecosystem.

Because the original project saw a decline in activity, Pydantic has assumed stewardship under the name httpx2. This ensures that a library critical to so many production environments receives consistent maintenance and timely security patches. Our goal is to maintain the original design philosophy and stability while carefully evolving the feature set.

---

🚀 Getting Started

To begin using the library, you can install it via pip:

pip install httpx2

Quick Start Checklist

• Install the package
• Import the library
• Execute your first request
• Verify the response status

Basic Usage Example

Here is how you can perform a simple GET request:

import httpx2

# Perform a synchronous request
r = httpx2.get('https://www.example.org/')

print(f"Response: {r}") # Response [200 OK]
print(f"Status: {r.status_code}") # 200
print(f"Content-Type: {r.headers['content-type']}") # 'text/html; charset=UTF-8'
print(f"Body: {r.text[:50]}...") # '!doctype html \n html \n head \n title Example...'

Command Line Interface (CLI)

If you prefer interacting with the web from your terminal, you can install the optional CLI component:

pip install 'httpx2[cli]'

Once installed, you can access the help menu and make requests directly: httpx2 --help

---

🛠 Key Features

HTTPX2 builds upon the intuitive API of requests while adding modern capabilities. The evolution can be viewed as: httpx $\rightarrow$ httpx2.

Core Capabilities

• API Compatibility: A broadly requests-compatible interface.
• Dual Mode: Standard sync interface with full async support.
• Direct Integration: Ability to call WSGI or ASGI applications directly.
• Network Management:
  • Connection Pooling & Keep-Alive.
  • HTTP(S) Proxy support.
  • Connection timeouts and streaming downloads.
• Security & Standards:
  • Browser-grade SSL verification.
  • Basic and Digest authentication.
  • .netrc support.
• Data Handling:
  • Automatic decompression and content decoding.
  • Unicode response bodies.
  • Multipart file uploads.
  • Elegant Key/Value cookie management and persistence via Sessions.
  • Support for International Domains and URLs.

Architecture Overview

The following diagram illustrates how HTTPX2 interacts with the underlying transport and target applications:

---

📊 Observability with Pydantic Logfire

HTTPX2 integrates seamlessly with Pydantic Logfire, an OpenTelemetry-based observability platform. You can get deep insights into your requests with minimal configuration.

Installation:

pip install 'logfire[httpx]'

Implementation:

import logfire
import httpx2

# This single line instruments all requests
logfire.configure() 

# Now, every request is traced automatically
httpx2.get("https://pydantic.dev/")

For more granular control, you can instrument specific client instances: logfire.instrument_httpx(client)

---

📦 Installation & Dependencies

Installation Options

Dependency Map

The project relies on several high-quality libraries to function:

• httpcore2: The primary transport layer.
• anyio: Provides structured concurrency for asyncio and trio.
• truststore: OS-native SSL verification.

Optional Extras:

• socksio: Required for httpx2[socks] (SOCKS proxy).
• rich & click: Required for httpx2[cli] (Terminal UI/CLI).
• brotli or brotlicffi: Required for httpx2[brotli] (Brotli decoding).
• backports.zstd: Required for httpx2[zstd] on Python $\le 3.13$.
  • Note: Python 3.14+ uses the native compression.zstd module.

---

📖 Documentation & Contribution

For a deeper dive, please visit the official documentation at https://httpx2.pydantic.dev/.

• QuickStart: For beginners.
• Advanced Usage: For complex implementations.
• Async & HTTP/2: Specialized guides for high-performance networking.
• Developer Interface: Full API reference.
• Third Party Packages: Integration tools.

Want to help? Please refer to the Contributing Guide to get started.

Final Credits

The design of this library is heavily inspired by the API layout of requests and the low-level networking architecture of urllib3.

We believe that the success of this project can be summarized by the formula: $\text{Reliability} = \text{Strong Foundation} + \text{Active Stewardship}$

---

Resources: Readme | BSD-3-Clause License | Code of Conduct | Security Policy