Install & Compatibility
Where this runs
tested against v1.0.9 · 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.930 runs
installs and imports cleanly · install 0.0s · import 0.409s · 24.8MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 2.3s · import 0.427s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
httpcore
✓ import httpcore
All public API is exposed at the top-level httpcore namespace
ConnectionPool
✓ import httpcore
http = httpcore.ConnectionPool()
✗ http = httpcore.SyncConnectionPool()
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
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())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'httpcore'
The 'httpcore' library is not installed in your current Python environment.
fixInstall the library using pip: `pip install httpcore`.
AttributeError: module 'httpcore' has no attribute 'TimeoutException'
This error typically occurs due to version incompatibility between `httpx` (which uses `httpcore`) and `httpcore`, where `httpx` expects an attribute that is missing or has been moved in the installed `httpcore` version.
fixUpgrade both `httpx` and `httpcore` to their latest compatible versions: `pip install --upgrade httpx httpcore`. If issues persist, try pinning to a known stable `httpx` version that is compatible with your `httpcore` installation (e.g., `pip install httpx==0.19.0`).
AttributeError: module 'httpcore' has no attribute 'NetworkBackend'
This `AttributeError` arises from changes in the `httpcore` package, specifically when an older version of the library attempts to access the `NetworkBackend` attribute which was removed or renamed in newer updates.
fixUpgrade your `httpcore` package to version 0.15.0 or higher: `pip install --upgrade httpcore`.
httpcore.ConnectError: [Errno 111] Connection refused
This error indicates that the client attempted to establish a connection to a server, but the server actively refused the connection. This can be due to the server being offline, a firewall blocking the connection, or the service not running on the specified host and port.
fixVerify that the target server is running, reachable, and listening on the correct IP address and port. Check any firewalls or network configurations that might be blocking the connection.
httpcore.ProxyError: 407 Proxy Authentication Required
This error means that the proxy server requires authentication credentials, but they were not provided or were incorrect.
fixEnsure that your proxy configuration includes the correct authentication credentials (username and password). For `httpx` (which uses `httpcore`), this can be done by providing them in the proxy URL, e.g., `proxies = {'all://': 'http://user:password@myproxy.com:8080'}`. Upgrade
Version history
1.0.9latest on PyPI · released Apr 24, 2025
Audit
Dependencies
h11requiredHTTP/1.1 protocol implementation; required by default install
anyiooptionalRequired for asyncio async backend (pip install httpcore[asyncio])
triooptionalRequired for trio async backend (pip install httpcore[trio])
h2optionalRequired for HTTP/2 support (pip install httpcore[http2])
socksiooptionalRequired for SOCKS proxy support (pip install httpcore[socks])