pip "WARNING: Retrying ... after connection broken" in CI

By Daniel Zoghalchali·Latchkey

pip’s underlying urllib3 retried a request after the connection to PyPI dropped. These warnings are transient network failures; the install often recovers on its own or on a re-run.

What this error means

pip prints repeated "WARNING: Retrying ... after connection broken" lines while fetching the index or a wheel, then either recovers or finally errors. Re-running the job usually succeeds with no code change.

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None,
status=None)) after connection broken by 'NewConnectionError(
'<pip._vendor.urllib3.connection.HTTPSConnection object at 0x...>:
Failed to establish a new connection: [Errno -3] Temporary failure
in name resolution')': /simple/requests/

Common causes

Transient connectivity or DNS blip

A brief network drop or DNS failure (Temporary failure in name resolution) breaks the connection. urllib3 retries; nothing is wrong with your project.

An overloaded or rate-limiting mirror

A busy PyPI mirror or proxy resets connections under load, so pip has to retry the request.

How to fix it

Raise retries and timeout

pip install --retries 5 --timeout 60 -r requirements.txt
# or persist
export PIP_RETRIES=5 PIP_DEFAULT_TIMEOUT=60

Cache wheels so retries matter less

Caching the pip cache means most wheels are already local, so a transient drop rarely fails the job.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ hashFiles('requirements.txt') }}

Check DNS/proxy if it persists

1. If you see name resolution failures, verify the runner’s DNS and any proxy settings.
2. Point pip at a closer or internal mirror for high-volume pipelines.
3. Pin a lockfile so the download set is stable and cacheable.

How to prevent it

• Set PIP_RETRIES/PIP_DEFAULT_TIMEOUT for resilience in CI.
• Cache the pip cache keyed on the lockfile.
• Use an internal mirror to reduce dependence on public PyPI.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation