httpcore

Warnings

• breaking CVE-2025-43859 (GHSA-vqfr-h8mv-ghfj): h11 <=0.15.0 accepts malformed Chunked-Encoding bodies enabling HTTP request smuggling (CVSS 9.1). httpcore <1.0.9 pulls in vulnerable h11. Upgrade to httpcore 1.0.9+ which requires h11>=0.16.0.
  Fix: pip install 'httpcore>=1.0.9' to pull in h11>=0.16.0 which fixes CVE-2025-43859.
• breaking Async support is NOT included in the default install since 1.0.0. Importing or instantiating AsyncConnectionPool without the async extras raises a RuntimeError at runtime, not at import time.
  Fix: Install the appropriate extra: pip install 'httpcore[asyncio]' or pip install 'httpcore[trio]'.
• gotcha Response headers (and request headers) are List[Tuple[bytes, bytes]], not a string-keyed dict. Comparing or accessing headers with plain strings will silently fail or raise a TypeError.
  Fix: Decode header names/values explicitly: [(k.decode(), v.decode()) for k, v in response.headers], or use a higher-level client like httpx which handles decoding for you.
• gotcha httpcore.request() and httpcore.stream() are top-level convenience helpers that open a new connection on every call. Using them in production code bypasses connection pooling entirely, causing a new TCP+TLS handshake per request.
  Fix: Instantiate httpcore.ConnectionPool() (or AsyncConnectionPool()) and reuse it across requests, ideally as a context manager.
• breaking The pre-1.0 class names SyncConnectionPool and SyncHTTPProxy were removed. Any code importing these names directly will raise an ImportError.
  Fix: Replace SyncConnectionPool with ConnectionPool and SyncHTTPProxy with HTTPProxy.
• gotcha Timeouts are passed via the request extensions dict, not as top-level kwargs: httpcore.request('GET', url, extensions={'timeout': {'connect': 5.0, 'read': 10.0}}). Passing timeout= as a keyword argument has no effect and is silently ignored.
  Fix: Always use extensions={'timeout': {'connect': N, 'read': N, 'write': N, 'pool': N}} to configure timeouts.
• gotcha response.content is only available after the full body has been read. When using httpcore.stream() or iterating response.iter_stream(), accessing response.content before calling response.read() raises an error.
  Fix: Call response.read() inside the stream context block before accessing response.content, or use httpcore.request() which reads the body automatically.

Install

• pip install httpcore HTTP/1.1 only (minimal, no async)
• pip install 'httpcore[asyncio]' With asyncio async support
• pip install 'httpcore[trio]' With trio async support
• pip install 'httpcore[http2]' With HTTP/2 support
• pip install 'httpcore[socks]' With SOCKS proxy support
• pip install 'httpcore[asyncio,http2,socks]' Full-featured install

Imports

• httpcore

  import httpcore

  All public API is exposed at the top-level httpcore namespace
• ConnectionPool

  import httpcore
  http = httpcore.ConnectionPool()

  SyncConnectionPool was the pre-1.0 name; use ConnectionPool in 1.x
• AsyncConnectionPool

  import httpcore
  http = httpcore.AsyncConnectionPool()

  Requires httpcore[asyncio] or httpcore[trio] to be installed
• HTTPProxy

  import httpcore
  proxy = httpcore.HTTPProxy(proxy_url='http://proxy:8080')

  Use proxy= kwarg on ConnectionPool() since 1.0.7 instead of wrapping manually
• request (top-level function)

  import httpcore
  response = httpcore.request('GET', 'https://example.com')

  Convenience function only; does not pool connections — use ConnectionPool for production

Quickstart

Demonstrates the one-off request helper, the recommended ConnectionPool pattern, streaming, and async usage.

import httpcore

# One-off request (no connection reuse)
response = httpcore.request('GET', 'https://httpbin.org/get')
print(response.status)   # int, e.g. 200
# Headers are List[Tuple[bytes, bytes]] — decode explicitly
for name, value in response.headers:
    print(name.decode(), value.decode())
print(response.content)  # bytes

# Production pattern: reuse a ConnectionPool
with httpcore.ConnectionPool() as http:
    r = http.request('GET', 'https://httpbin.org/get')
    print(r.status)

# Streaming large response
with httpcore.stream('GET', 'https://httpbin.org/stream-bytes/1024') as r:
    for chunk in r.iter_stream():
        pass  # process chunk (bytes)

# Async (requires: pip install 'httpcore[asyncio]')
import asyncio

async def main():
    async with httpcore.AsyncConnectionPool() as http:
        r = await http.request('GET', 'https://httpbin.org/get')
        print(r.status)

asyncio.run(main())