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 pip cannot establish a connection to a configured HTTP(S) proxy while downloading a package. It is produced inside raise_connection_error() after urllib3 exhausts its retries and reports the final failure reason as a urllib3 ProxyError. The proxy URL in the message is redacted of credentials via redact_auth_from_url.

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 d7d0d0a394)

Solutions

Verify the proxy URL is reachable: test with curl -x <proxy_url> <package_url> or nc -vz <proxy_host> <proxy_port>.
Check pip's effective proxy config: pip config list and echo $HTTP_PROXY $HTTPS_PROXY.
Remove or correct the proxy setting: pip install --proxy '' <pkg> or unset HTTP_PROXY HTTPS_PROXY if a stale proxy env var leaks into the shell.
If the proxy requires auth, ensure credentials are embedded correctly in the URL (https://user:pass@host:port) and that the proxy supports CONNECT tunneling for HTTPS.
Retry after confirming network/firewall allows outbound traffic to the proxy host and port.

Example fix

# before
export HTTPS_PROXY=http://prox.my-corp.com:8080
pip install requests

# after (corrected hostname)
export HTTPS_PROXY=http://proxy.my-corp.com:8080
pip install requests

Defensive patterns

Strategy: retry

Validate before calling

import socket, urllib.parse
proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("HTTP_PROXY")
if proxy:
    parsed = urllib.parse.urlparse(proxy)
    host, port = parsed.hostname, parsed.port or (443 if parsed.scheme == "https" else 80)
    try:
        socket.create_connection((host, port), timeout=5).close()
    except OSError as e:
        raise SystemExit(f"proxy unreachable: {host}:{port} -> {e}")

Try / catch

from pip._internal.exceptions import ProxyConnectionError
try:
    install_pkg(req)
except ProxyConnectionError as e:
    logger.warning("proxy down; retrying without proxy: %s", e)
    run([sys.executable, "-m", "pip", "install", "--proxy", "", req])

Prevention

Validate proxy reachability in CI before running pip.
Pin proxy config in pip.conf rather than relying on shell env vars that can leak across tools.
Configure --retries and --timeout so transient proxy blips self-heal.

When it happens

Trigger: A proxy is configured (via --proxy, HTTP_PROXY/HTTPS_PROXY env vars, or pip config) and the TCP connection to that proxy host:port fails or the proxy refuses the CONNECT tunnel. The urllib3 MaxRetryError.reason is an instance of urllib3.exceptions.ProxyError at utils.py:199-201.

Common situations: Corporate networks behind a proxy where the proxy hostname is mistyped, the port is blocked by a firewall, the proxy is temporarily down, or credentials are wrong. Also common when HTTPS_PROXY points to an HTTP-only proxy that cannot tunnel HTTPS, or when a VPN drops mid-download.

Related errors

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