Registry / http-networking / httpx-socks

httpx-socks

library0.11.0pypypi✓ verified 84d ago

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.

http-networking

pip install httpx-socks

github ↗package ↗

INSTALL

IMPORT

SIG · HTTPX-SOCKS

httpx-socks

http-networkingpythonv0.11.0

Install

2.2s avg

Import

505ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.11.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.526s · 22.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.484s · 23MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SyncProxyTransport

✓ from httpx_socks import SyncProxyTransport

AsyncProxyTransport

✓ from httpx_socks import AsyncProxyTransport

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())

Debug

Known issues

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.

affects: all

deprecatedThe `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)`.

affects: 0.10.0+

breakingAs 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`

affects: httpx>=0.28

gotchaProxy 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`

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'httpx_socks'

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

fix

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

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

Attempting to import the internal class `ProxyTransport` directly.

fix

Use `from httpx_socks import SyncProxyTransport` or `AsyncProxyTransport`.

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

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://...')`

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

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

fix

Verify the proxy hostname and check network connectivity.

Upgrade

Version history

0.11.0latest on PyPI · released Dec 5, 2025

Audit

Dependencies

httpxrequiredCore dependency; httpx is needed to use the transports.

PySocksrequiredRequired for SOCKS proxy support.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/romis2012/httpx-socks ↗

packagehttps://pypi.org/project/httpx-socks/ ↗