{"record":{"id":"7d0cbb8d13fd92f5","repo":"psf/requests","slug":"missing-dependencies-for-socks-support","errorCode":null,"errorMessage":"Missing dependencies for SOCKS support.","messagePattern":"Missing dependencies for SOCKS support\\.","errorType":"exception","errorClass":"InvalidSchema","httpStatus":null,"severity":"error","filePath":"src/requests/adapters.py","lineNumber":67,"sourceCode":"    SSLError,\n)\nfrom .models import Response\nfrom .structures import CaseInsensitiveDict\nfrom .utils import (\n    DEFAULT_CA_BUNDLE_PATH,\n    get_auth_from_url,\n    get_encoding_from_headers,\n    prepend_scheme_if_needed,\n    select_proxy,\n    urldefragauth,\n)\n\ntry:\n    from urllib3.contrib.socks import SOCKSProxyManager  # type: ignore[assignment]\nexcept ImportError:\n\n    def SOCKSProxyManager(*args: Any, **kwargs: Any) -> None:\n        raise InvalidSchema(\"Missing dependencies for SOCKS support.\")\n\n\nif typing.TYPE_CHECKING:\n    from urllib3.connectionpool import HTTPConnectionPool\n    from urllib3.poolmanager import PoolManager as _PoolManager\n\n    from . import _types as _t\n    from .models import PreparedRequest\n\nfrom ._types import is_prepared as _is_prepared\n\nDEFAULT_POOLBLOCK = False\nDEFAULT_POOLSIZE = 10\nDEFAULT_RETRIES = 0\nDEFAULT_POOL_TIMEOUT = None\n\n\ndef _urllib3_request_context(","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/psf/requests/blob/8068356288978c4f54661ae6f95afe0e0831885e/src/requests/adapters.py#L49-L85","documentation":"This error is raised by a stub SOCKSProxyManager that replaces the real one when the optional PySocks dependency is absent. The requests library imports SOCKSProxyManager from urllib3.contrib.socks, which itself requires the 'PySocks' package. If that import fails at module load time, requests installs a fallback function that raises InvalidSchema with this message whenever a SOCKS proxy URL (socks5://, socks4://, etc.) is actually used.","triggerScenarios":"Triggered when the caller passes a SOCKS proxy (e.g. socks5://127.0.0.1:1080) via the proxies argument, the requests session proxies, or HTTP(S)_PROXY/ALL_PROXY environment variables, while PySocks is not installed in the environment. It fires lazily: only when proxy_manager_for constructs a SOCKSProxyManager for the SOCKS scheme, never at import time.","commonSituations":"Most common cause is installing requests via a minimal extras spec that omits the socks extra, or deploying a fresh virtualenv/CI image where 'pip install requests' was run without 'requests[socks]'. Also seen after dependency-pin lock-file updates that drop PySocks, or when copying a working proxy config to a new container that lacks the wheel.","solutions":["Install the SOCKS extra: pip install 'requests[socks]' (or pip install PySocks requests).","Verify PySocks is importable in the same interpreter the app uses: python -c \"import socks; print(socks.__version__)\".","If SOCKS is unintended, switch the proxy config to an http:// or https:// proxy so the stub is never invoked.","For lock-file based setups (pip-tools, Poetry, PDM), regenerate the lock so PySocks is pinned and present.","In Docker/CI images, add PySocks to the requirements stage and confirm it is copied into the final image."],"exampleFix":"# before\npip install requests\n# proxies={\"http\": \"socks5://127.0.0.1:1080\"}  -> InvalidSchema\n\n# after\npip install 'requests[socks]'","handlingStrategy":"validation","validationCode":"# Before configuring any SOCKS proxy, confirm PySocks is importable.\nimport importlib.util\n\n_wants_socks = any(\n    str(p).lower().startswith(\"socks\")\n    for p in (proxies or {}).values()\n    if p\n)\nif _wants_socks and importlib.util.find_spec(\"socks\") is None:\n    raise RuntimeError(\n        \"SOCKS proxy requested but PySocks is not installed. \"\n        \"Install with: pip install 'requests[socks]'\"\n    )","typeGuard":"from urllib3.util import parse_url\n\ndef is_usable_proxy(proxy: str | None) -> bool:\n    \"\"\"True if proxy is None/empty (no proxy) or a non-SOCKS scheme,\n    OR a SOCKS scheme with PySocks available.\"\"\"\n    if not proxy:\n        return True\n    scheme = (parse_url(proxy).scheme or \"\").lower()\n    if scheme.startswith(\"socks\"):\n        import importlib.util\n        return importlib.util.find_spec(\"socks\") is not None\n    return True","tryCatchPattern":"import requests.exceptions as exc\n\ntry:\n    resp = session.get(url, proxies=proxies)\nexcept exc.InvalidSchema as e:\n    if \"SOCKS\" in str(e):\n        raise RuntimeError(\n            \"SOCKS proxy requested but PySocks missing; \"\n            \"run: pip install 'requests[socks]'\"\n        ) from e\n    raise","preventionTips":["Declare requests[socks] in requirements whenever proxy config may include SOCKS.","At app startup, detect SOCKS proxies in config/env and assert PySocks is importable.","Pin PySocks in lock files; treat its absence as a deployment-blocking error.","Never assume requests ships SOCKS support by default."],"tags":["proxy","socks","dependencies","install","invalid-schema"],"backgroundTag":null,"analyzedSha":"8068356288978c4f54661ae6f95afe0e0831885e","analyzedAt":"2026-08-11T20:11:09.238Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}