psf/requests · error · InvalidSchema

Missing dependencies for SOCKS support.

Error message

Missing dependencies for SOCKS support.

What it means

requests raises InvalidSchema('Missing dependencies for SOCKS support.') when a request is routed through a socks:// proxy but urllib3's SOCKS extras are not installed. At import time adapters.py tries `from urllib3.contrib.socks import SOCKSProxyManager`; on ImportError it substitutes a stub function that raises this error the moment a SOCKS proxy manager is actually needed. This makes SOCKS an optional feature that fails lazily rather than at import.

Source

Thrown at src/requests/adapters.py:67

    SSLError,
)
from .models import Response
from .structures import CaseInsensitiveDict
from .utils import (
    DEFAULT_CA_BUNDLE_PATH,
    get_auth_from_url,
    get_encoding_from_headers,
    prepend_scheme_if_needed,
    select_proxy,
    urldefragauth,
)

try:
    from urllib3.contrib.socks import SOCKSProxyManager  # type: ignore[assignment]
except ImportError:

    def SOCKSProxyManager(*args: Any, **kwargs: Any) -> None:
        raise InvalidSchema("Missing dependencies for SOCKS support.")


if typing.TYPE_CHECKING:
    from urllib3.connectionpool import HTTPConnectionPool
    from urllib3.poolmanager import PoolManager as _PoolManager

    from . import _types as _t
    from .models import PreparedRequest

from ._types import is_prepared as _is_prepared

DEFAULT_POOLBLOCK = False
DEFAULT_POOLSIZE = 10
DEFAULT_RETRIES = 0
DEFAULT_POOL_TIMEOUT = None


def _urllib3_request_context(

View on GitHub ↗ (pinned to 414f0513c3)

Solutions

1. Install the SOCKS extra: pip install 'requests[socks]' (or pip install PySocks / 'urllib3[socks]')
2. If you didn't intend to use a SOCKS proxy, unset ALL_PROXY/HTTP_PROXY/HTTPS_PROXY env vars pointing at socks:// URLs, or pass proxies={} / session.trust_env=False
3. For DNS resolution through the proxy, use the socks5h:// scheme after installing the extra

Example fix

# before
# pip install requests
requests.get(url, proxies={'https': 'socks5://127.0.0.1:1080'})  # InvalidSchema

# after
# pip install 'requests[socks]'
requests.get(url, proxies={'https': 'socks5h://127.0.0.1:1080'})

import importlib.util
has_socks = importlib.util.find_spec("socks") is not None
if not has_socks:
    raise RuntimeError("Install requests[socks] before using a socks:// proxy")

try:
    resp = session.get(url, proxies={"https": "socks5://host:1080"})
except ImportError as e:
    # 'Missing dependencies for SOCKS support.'
    raise RuntimeError("SOCKS proxy configured but PySocks not installed; pip install 'requests[socks]'") from e

When it happens

Trigger: Calling requests.get/post with proxies={'https': 'socks5://host:port'} (or socks4/socks5h schemes), or having ALL_PROXY/HTTPS_PROXY env vars set to a socks:// URL, in an environment where PySocks/urllib3[socks] is not installed. The stub SOCKSProxyManager at src/requests/adapters.py:66 raises when HTTPAdapter.proxy_manager_for resolves a socks-scheme proxy.

Common situations: Fresh virtualenvs or Docker images where `requests` was installed without the `[socks]` extra; a system-wide ALL_PROXY=socks5://... environment variable (common with shadowsocks/ssh -D setups) silently affecting scripts; CI environments that differ from a dev machine where PySocks happened to be present.

Related errors

• Please check proxy URL. It is malformed and could be missing
• Files must be provided.
• Data must not be a string.
• Unsupported event specified, with event name "{event}"
• Invalid URL {url!r}: No scheme supplied. Perhaps you meant h

AI-assisted analysis of psf/requests@414f0513c3 (2026-07-31). Data as JSON: /data/errors/7d0cbb8d13fd92f5.json. Report an issue: GitHub ↗.