pypa/pip · error · InvalidSchema

Missing dependencies for SOCKS support.

Error message

Missing dependencies for SOCKS support.

What it means

Requests defines a stub SOCKSProxyManager that raises InvalidSchema('Missing dependencies for SOCKS support.') when urllib3.contrib.socks could not be imported (PySocks not installed). The stub is only invoked if a request is routed through a socks:// (or socks4/socks5) proxy, so the error surfaces at request time, not import time.

Source

Thrown at src/pip/_vendor/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 pip._vendor.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 pip._vendor.urllib3.connectionpool import HTTPConnectionPool
    from pip._vendor.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 d7d0d0a394)

Solutions

1. Install PySocks: 'pip install pysocks' (or 'pip install requests[socks]').
2. Switch the proxy to an HTTP/HTTPS proxy if SOCKS is not required.
3. Ensure the SOCKS URL includes the scheme version, e.g. socks5h:// for remote DNS, after installing the dependency.

Example fix

# before
pip install --proxy socks5://127.0.0.1:1080 pkg
# -> InvalidSchema: Missing dependencies for SOCKS support.

# after
pip install pysocks
pip install --proxy socks5://127.0.0.1:1080 pkg

try:
    import socks  # noqa: F401
except ImportError:
    has_socks = False
else:
    has_socks = True
if proxy_url.lower().startswith('socks') and not has_socks:
    raise RuntimeError('install PySocks (pip install requests[socks]) to use a SOCKS proxy')

from pip._vendor.requests.exceptions import InvalidSchema
try:
    resp = session.get(url, proxies={'http': 'socks5://127.0.0.1:1080'})
except InvalidSchema as e:
    if 'SOCKS' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'pysocks'])

When it happens

Trigger: Calling requests with a SOCKS proxy URL (e.g. proxies={'http':'socks5://127.0.0.1:1080'}) on an environment where the 'PySocks' (import name 'socks') package is not installed; pip vendors requests, so this triggers when pip is told to use a SOCKS proxy without the socks extra.

Common situations: Setting ALL_PROXY/HTTP_PROXY to a socks5:// URL without installing PySocks; corporate/privacy proxies (Tor, shadowsocks) used for pip; minimal containers that stripped the socks dependency.

Related errors

• Please check proxy URL. It is malformed and could be missing
• proxy-connection-failed
• failed-build-dependency-install
• No matching distribution found for {query}
• XMLRPC request failed [code: {fault.faultCode}] {fault.fault

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/00ea4a849d7f5bf7.json. Report an issue: GitHub.