pypa/pip · error · ProxyConnectionError

proxy-connection-failed

proxy-connection-failed

Error message

Failed to connect to proxy {proxy} while fetching {url}

What it means

Raised as ProxyConnectionError when, after narrowing a MaxRetryError, the terminal reason is a urllib3.exceptions.ProxyError: pip could not connect to the configured HTTP(S) proxy. The message names the proxy and the URL being fetched.

Solutions

1. Verify the proxy host:port is up and reachable (curl --proxy ...).
2. Correct or remove HTTPS_PROXY/HTTP_PROXY env vars and the --proxy option.
3. Provide proxy credentials if the proxy requires auth.
4. Ensure no_proxy excludes the index host only if intended.

Example fix

# before
HTTPS_PROXY=http://proxy.corp:3128 pip install pkg   # proxy down

# after
unset HTTPS_PROXY HTTP_PROXY && pip install pkg

import os, socket

def proxy_reachable() -> bool:
    proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("HTTP_PROXY")
    if not proxy:
        return True
    from urllib.parse import urlsplit
    p = urlsplit(proxy)
    try:
        with socket.create_connection((p.hostname, p.port or 8080), timeout=5):
            return True
    except OSError:
        return False

from pip._internal.exceptions import ProxyConnectionError

try:
    run_pip_install(["pkg"])
except ProxyConnectionError:
    # unset stale proxy and retry, or fix proxy config
    for k in ("HTTPS_PROXY", "HTTP_PROXY"):
        os.environ.pop(k, None)
    run_pip_install(["pkg"])

When it happens

Trigger: HTTPS_PROXY/HTTP_PROXY env vars or --proxy point at a proxy that is down, refusing connections, requiring unavailable auth, or unreachable; pip's connection pool reports a ProxyError on the final retry.

Common situations: Corporate proxy offline after VPN disconnect; stale proxy env vars on a developer machine; proxy port wrong; proxy requires auth that was not configured; proxy TLS intercept failing.

Related errors

• connection-failed
• connection-timeout
• Could not install requirement
• Error reading pylock file
• incomplete-download

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/52d88de5d1ba66e3. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_internal/network/utils.py:201

    if not isinstance(reason, urllib3.exceptions.MaxRetryError):
        raise ConnectionFailedError(url, raw_hostname, reason)

    max_retry_error = reason
    assert isinstance(max_retry_error.pool, urllib3.connectionpool.HTTPConnectionPool)
    host = max_retry_error.pool.host
    proxy = max_retry_error.pool.proxy
    # Narrow the reason further to the specific error from the last retry.
    reason = max_retry_error.reason

    if isinstance(reason, urllib3.exceptions.SSLError):
        raise SSLVerificationError(url, host, reason)
    if isinstance(reason, urllib3.exceptions.TimeoutError) and not isinstance(
        reason, urllib3.exceptions.NewConnectionError
    ):
        _raise_timeout_error(reason, url, host, timeout)
    if isinstance(reason, urllib3.exceptions.ProxyError):
        assert proxy is not None
        raise ProxyConnectionError(url, redact_auth_from_url(str(proxy)), reason)

    # Unknown error, give up and raise a generic error.
    raise ConnectionFailedError(
        url, host, reason if isinstance(reason, Exception) else max_retry_error
    )

View on GitHub (pinned to f399c37189)