encode/httpx · critical · ImportError

Using SOCKS proxy, but the 'socksio' package is not installe

Error message

Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using `pip install httpx[socks]`.

What it means

Raised by the synchronous HTTPTransport constructor when a SOCKS proxy ('socks5' or 'socks5h' scheme) is configured but the optional 'socksio' dependency is not importable. httpx delegates SOCKS proxying to httpcore, which requires socksio; without it the transport cannot be built. The error is an ImportError raised at construction time (in __init__ of AsyncHTTPTransport/HTTPTransport), before any request is sent.

Source

Thrown at httpx/_transports/default.py:191

                    port=proxy.url.port,
                    target=proxy.url.raw_path,
                ),
                proxy_auth=proxy.raw_auth,
                proxy_headers=proxy.headers.raw,
                ssl_context=ssl_context,
                proxy_ssl_context=proxy.ssl_context,
                max_connections=limits.max_connections,
                max_keepalive_connections=limits.max_keepalive_connections,
                keepalive_expiry=limits.keepalive_expiry,
                http1=http1,
                http2=http2,
                socket_options=socket_options,
            )
        elif proxy.url.scheme in ("socks5", "socks5h"):
            try:
                import socksio  # noqa
            except ImportError:  # pragma: no cover
                raise ImportError(
                    "Using SOCKS proxy, but the 'socksio' package is not installed. "
                    "Make sure to install httpx using `pip install httpx[socks]`."
                ) from None

            self._pool = httpcore.SOCKSProxy(
                proxy_url=httpcore.URL(
                    scheme=proxy.url.raw_scheme,
                    host=proxy.url.raw_host,
                    port=proxy.url.port,
                    target=proxy.url.raw_path,
                ),
                proxy_auth=proxy.raw_auth,
                ssl_context=ssl_context,
                max_connections=limits.max_connections,
                max_keepalive_connections=limits.max_keepalive_connections,
                keepalive_expiry=limits.keepalive_expiry,
                http1=http1,
                http2=http2,

View on GitHub (pinned to b5addb64f0)

Solutions

1. Install the SOCKS extra: pip install 'httpx[socks]' (adds the socksio package).
2. Verify the install in the same environment/runtime that runs the code: python -c 'import socksio'.
3. If SOCKS support is not actually needed, change the proxy URL scheme to 'http' or 'https' (a plain HTTP forward proxy), or remove the proxy argument.
4. Pin the extra in requirements.txt/pyproject.toml so it is not lost on rebuilds (httpx[socks]).

Example fix

// before
client = httpx.Client(proxy="socks5://127.0.0.1:1080")  # ImportError: socksio missing

// after
# pip install 'httpx[socks]'
client = httpx.Client(proxy="socks5://127.0.0.1:1080")

def assert_socks_supported() -> None:
    try:
        import socksio  # noqa: F401
    except ImportError as e:
        raise RuntimeError(
            "SOCKS proxy requested but socksio is missing. "
            "Install with: pip install 'httpx[socks]'"
        ) from e

# call before constructing httpx.Client(proxy='socks5://...')
assert_socks_supported()

def is_socks_proxy_url(proxy: str) -> bool:
    return proxy.lower().startswith(("socks5://", "socks5h://"))

try:
    client = httpx.Client(proxy="socks5://127.0.0.1:1080")
except ImportError as e:
    if "socksio" in str(e):
        raise SystemExit("Missing optional dependency. Run: pip install 'httpx[socks]'") from e
    raise

When it happens

Trigger: Constructing httpx.HTTPClient(proxy='socks5://127.0.0.1:1080') or httpx.Client(mounts={'all://': httpx.HTTPTransport(proxy='socks5://...')}) on an environment where 'import socksio' fails. Also triggered by an HTTP_PROXY/HTTPS_PROXY-style env var resolution that yields a socks5 URL while trust_env=True.

Common situations: Installing httpx with a plain 'pip install httpx' (no extras) and then pointing at a Tor / SSH / corporate SOCKS proxy; copying code that worked on a machine with the socks extra into a slim Docker image; upgrading httpx without re-adding the [socks] extra.

Related errors

• Proxy protocol must be either 'http', 'https', 'socks5', or
• Using http2=True, but the 'h2' package is not installed. Mak
• Cannot send a request, as the client has been closed.
• Exceeded maximum allowed redirects.
• Attempted to send an async request with a sync Client instan

AI-assisted analysis of encode/httpx@b5addb64f0 (2026-08-04). Data as JSON: /data/errors/1b47d13ebf242d8e.json. Report an issue: GitHub.