pip "Max retries exceeded with url" (HTTPSConnectionPool) in CI

pip retried the index repeatedly and still could not connect, so it gave up with "Max retries exceeded." This is usually transient network trouble, but a persistent one points at DNS, a proxy, or a blocked host.

What this error means

pip fails to reach PyPI (or a mirror) with HTTPSConnectionPool(host=..., port=443): Max retries exceeded with url. It often follows a string of "Retrying" warnings and may pass on a re-run if the cause was transient.

Could not fetch URL https://pypi.org/simple/flask/: There was a problem
confirming the ssl certificate: HTTPSConnectionPool(host='pypi.org', port=443):
Max retries exceeded with url: /simple/flask/ (Caused by
NewConnectionError(... Failed to establish a new connection: [Errno 111]
Connection refused))

Common causes

Transient outage or rate limit

A brief outage, throttling, or a flaky link exhausts pip’s retries. The same command often works minutes later.

Proxy or firewall blocking the host

A corporate proxy, egress firewall, or missing proxy env vars (HTTPS_PROXY) leaves pip unable to reach the index at all - Connection refused rather than a timeout.

How to fix it

Raise retries and timeout, then re-run

pip install --retries 5 --timeout 60 -r requirements.txt

Configure the proxy if egress is restricted

When the runner must go through a proxy, set the proxy env vars (or pip’s flag) so pip can reach the index.

export HTTPS_PROXY=http://proxy.internal:3128
export HTTP_PROXY=http://proxy.internal:3128
pip install -r requirements.txt
# or per command
pip install --proxy http://proxy.internal:3128 -r requirements.txt

Use a reachable internal mirror

1. Point pip at an internal index that the runner can reach without public egress.
2. Verify connectivity with curl -I https://pypi.org/simple/ from the same step.
3. Cache the pip cache so most installs do not hit the network.

How to prevent it

• Set PIP_RETRIES/PIP_DEFAULT_TIMEOUT for resilience.
• Configure proxy env vars consistently on restricted runners.
• Host or proxy an internal index to avoid public-network flakiness.

Related guides