{"id":"1b47d13ebf242d8e","repo":"encode/httpx","slug":"using-socks-proxy-but-the-socksio-package-is-no","errorCode":null,"errorMessage":"Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using `pip install httpx[socks]`.","messagePattern":"Using SOCKS proxy, but the 'socksio' package is not installed\\. Make sure to install httpx using `pip install httpx\\[socks\\]`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"httpx/_transports/default.py","lineNumber":191,"sourceCode":"                    port=proxy.url.port,\n                    target=proxy.url.raw_path,\n                ),\n                proxy_auth=proxy.raw_auth,\n                proxy_headers=proxy.headers.raw,\n                ssl_context=ssl_context,\n                proxy_ssl_context=proxy.ssl_context,\n                max_connections=limits.max_connections,\n                max_keepalive_connections=limits.max_keepalive_connections,\n                keepalive_expiry=limits.keepalive_expiry,\n                http1=http1,\n                http2=http2,\n                socket_options=socket_options,\n            )\n        elif proxy.url.scheme in (\"socks5\", \"socks5h\"):\n            try:\n                import socksio  # noqa\n            except ImportError:  # pragma: no cover\n                raise ImportError(\n                    \"Using SOCKS proxy, but the 'socksio' package is not installed. \"\n                    \"Make sure to install httpx using `pip install httpx[socks]`.\"\n                ) from None\n\n            self._pool = httpcore.SOCKSProxy(\n                proxy_url=httpcore.URL(\n                    scheme=proxy.url.raw_scheme,\n                    host=proxy.url.raw_host,\n                    port=proxy.url.port,\n                    target=proxy.url.raw_path,\n                ),\n                proxy_auth=proxy.raw_auth,\n                ssl_context=ssl_context,\n                max_connections=limits.max_connections,\n                max_keepalive_connections=limits.max_keepalive_connections,\n                keepalive_expiry=limits.keepalive_expiry,\n                http1=http1,\n                http2=http2,","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/encode/httpx/blob/b5addb64f0161ff6bfe94c124ef76f6a1fba5254/httpx/_transports/default.py#L173-L209","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the SOCKS extra: pip install 'httpx[socks]' (adds the socksio package).","Verify the install in the same environment/runtime that runs the code: python -c 'import socksio'.","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.","Pin the extra in requirements.txt/pyproject.toml so it is not lost on rebuilds (httpx[socks])."],"exampleFix":"// before\nclient = httpx.Client(proxy=\"socks5://127.0.0.1:1080\")  # ImportError: socksio missing\n\n// after\n# pip install 'httpx[socks]'\nclient = httpx.Client(proxy=\"socks5://127.0.0.1:1080\")","handlingStrategy":"validation","validationCode":"def assert_socks_supported() -> None:\n    try:\n        import socksio  # noqa: F401\n    except ImportError as e:\n        raise RuntimeError(\n            \"SOCKS proxy requested but socksio is missing. \"\n            \"Install with: pip install 'httpx[socks]'\"\n        ) from e\n\n# call before constructing httpx.Client(proxy='socks5://...')\nassert_socks_supported()","typeGuard":"def is_socks_proxy_url(proxy: str) -> bool:\n    return proxy.lower().startswith((\"socks5://\", \"socks5h://\"))","tryCatchPattern":"try:\n    client = httpx.Client(proxy=\"socks5://127.0.0.1:1080\")\nexcept ImportError as e:\n    if \"socksio\" in str(e):\n        raise SystemExit(\"Missing optional dependency. Run: pip install 'httpx[socks]'\") from e\n    raise","preventionTips":["Declare httpx[socks] (not bare httpx) in pyproject.toml when SOCKS is used.","Run a startup self-check: import socksio, in the same env as the app.","Keep SOCKS usage behind a feature flag so non-SOCKS deployments stay slim."],"tags":["proxy","socks","dependency","sync","network"],"analyzedSha":"b5addb64f0161ff6bfe94c124ef76f6a1fba5254","analyzedAt":"2026-08-04T19:32:56.768Z","schemaVersion":2}