WARNING: Retrying (...) after connection broken by ... (timeouts / proxy / SSL negotiation)

What This Error Means

pip is repeatedly failing to reach the package index due to network timeouts, proxy issues, or TLS incompatibilities, and it is retrying until it gives up.

How to Fix It

1. Increase retries/timeouts for slow networks: --retries and --timeout.
2. If a proxy is required, configure it for pip (pip config or environment variables) and ensure the proxy URL scheme is correct.
3. If TLS errors mention protocol version, upgrade Python (and OpenSSL) to a version that supports the required TLS versions.
4. Prefer using an internal mirror/repository manager reachable from your network to stabilize installs.

Why It Happens

• Slow or unstable network causes connect/read timeouts.
• A corporate proxy or VPN requires configuration (or is intercepting TLS).
• TLS protocol mismatch (old Python/OpenSSL cannot negotiate with modern TLS requirements).
• Firewall blocks outbound HTTPS to PyPI (or blocks DNS).

How to Verify

1. Re-run the install and confirm pip can fetch /simple/ pages and artifacts without exhausting retries.
2. Run python -m pip install -v pip (or another small package) to confirm basic index connectivity.

Manual network/proxy/TLS checks

1. Confirm the index URL: python -m pip config list (look for global.index-url / global.extra-index-url).
2. If behind a proxy, confirm proxy config and environment variables are correct.
3. Retry once with verbose output: python -m pip install -v ... and note the first failure type (timeout vs TLS vs proxy).

Common CLI Output

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'ConnectTimeoutError(... timed out. (connect timeout=15)')': /simple/<project>/

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'ReadTimeoutError("HTTPSConnectionPool(host='pypi.org', port=443): Read timed out. (read timeout=15)")': /simple/<project>/

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'ProxyError('Cannot connect to proxy.', ... )': /simple/<project>/

Could not fetch URL https://pypi.python.org/simple/pip/: There was a problem confirming the ssl certificate: [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version ... - skipping

How pip downloads packages

1. pip downloads package metadata and files over HTTP(S).
2. Transient failures (timeouts/resets) or consistent failures (wrong proxy settings, blocked domains, TLS version mismatch) cause retries.
3. If the root cause persists, the operation fails after the retry budget is exhausted.

Prevention Tips

• Use an internal mirror/repository manager for CI and corporate networks.
• Keep Python/pip updated to maintain modern TLS support.
• Standardize proxy configuration across developer machines and runners.

Where This Can Be Triggered

        if not conn:
            # Try again
            log.warning(
                "Retrying (%r) after connection broken by '%r': %s", retries, err, url
            )
            return self.urlopen(
                method,
                url,
                body,
                headers,
                retries,
                redirect,
                assert_same_host,
                timeout=timeout,
                pool_timeout=pool_timeout,
                release_conn=release_conn,
                chunked=chunked,
                body_pos=body_pos,
                **response_kw
            )