httpx-socks

0.11.0 verified Mon Apr 27 auth: no python

Provides proxy transports (HTTP, SOCKS4, SOCKS5) for httpx, enabling proxy support for both sync and async httpx clients. Currently at version 0.11.0, released with support for Python >=3.8. The library wraps httpx transports using PySocks and optionally trio for async. Releases are infrequent, with the last update in 2024.

pip install httpx-socks

Common errors

error ModuleNotFoundError: No module named 'httpx_socks' ↓

cause The package is not installed or installed in an incorrect environment.

fix

Run pip install httpx-socks in the correct Python environment.

error AttributeError: module 'httpx_socks' has no attribute 'ProxyTransport' ↓

cause Attempting to import the internal class `ProxyTransport` directly.

fix

Use from httpx_socks import SyncProxyTransport or AsyncProxyTransport.

error TypeError: SyncProxyTransport.from_url() got an unexpected keyword argument 'proxy_type' ↓

cause Trying to pass kwargs that are not expected in `from_url`. The method accepts a URL string only.

fix

Pass the proxy URL as the first positional argument: ...from_url('socks5://...')

error httpx.ConnectError: [Errno -2] Name or service not known ↓

cause The proxy hostname in the URL cannot be resolved (DNS failure).

fix

Verify the proxy hostname and check network connectivity.

Warnings

gotcha `SyncProxyTransport` and `AsyncProxyTransport` are the only supported transports. Do NOT import `ProxyTransport` directly as it is an internal class. ↓

fix Always use `SyncProxyTransport` for sync clients and `AsyncProxyTransport` for async clients.

deprecated The `from_url` class method is the only recommended way to create a transport. Directly instantiating transports with `proxy_type`, etc., may be removed in future versions. ↓

fix Use `SyncProxyTransport.from_url(url)` or `AsyncProxyTransport.from_url(url)`.

breaking As of httpx 0.28.0, the transport interface changed, and older versions of httpx-socks may break. Ensure httpx and httpx-socks versions are compatible (e.g., httpx>=0.28 with httpx-socks 0.11+). ↓

fix Upgrade both to latest: `pip install -U httpx httpx-socks`

gotcha Proxy authentication for SOCKS5 requires `user:pass` in the URL. Without 'user:pass' in the URL, the transport will not authenticate even if the proxy expects it. ↓

fix Include credentials in the URL: `socks5://username:password@host:port`

Imports

SyncProxyTransport

from httpx_socks import SyncProxyTransport

AsyncProxyTransport

from httpx_socks import AsyncProxyTransport

Quickstart

Create a sync httpx client with SOCKS5 proxy authentication.

import httpx
from httpx_socks import SyncProxyTransport

transport = SyncProxyTransport.from_url('socks5://user:pass@proxy.example.com:1080')

with httpx.Client(transport=transport) as client:
    response = client.get('http://httpbin.org/ip')
    print(response.json())