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/

Diagnose it: which Python, and which index?

A pip failure in CI is usually about the interpreter or the index rather than the package. Runners have several Pythons installed, and the one on PATH is not necessarily the one your virtualenv or your workflow selected.

which -a python python3 pip pip3
python -c "import sys; print(sys.executable, sys.version)"
pip config list
pip debug --verbose 2>/dev/null | grep -i "compatible tags" | head -5

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