pip "ReadTimeoutError" / connection failure in CI

pip opened a connection to the index but the download stalled past its timeout, or the connection dropped mid-transfer. This is usually transient network flakiness rather than a bad request.

What this error means

pip prints "ReadTimeoutError: HTTPSConnectionPool(...): Read timed out." or "Connection broken" and may retry a few times before failing the job.

pip

WARNING: Retrying (Retry(total=4, ...)) after connection broken by
'ReadTimeoutError("HTTPSConnectionPool(host='files.pythonhosted.org', port=443):
Read timed out. (read timeout=15)")': /packages/...

Common causes

Transient network slowness to the index

A slow mirror, a large wheel, or momentary packet loss makes the download exceed the read timeout.

A too-short default timeout for large packages

Big binary wheels over a congested link can outlast pip's default timeout on a single attempt.

How to fix it

Raise the timeout and retries

Give pip more time and attempts so a slow download completes instead of aborting the job.

Terminal

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

Cache wheels to avoid re-downloading

Persist the pip cache across runs so packages that already downloaded once are not fetched again.

.github/workflows/ci.yml

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

How to prevent it

Cache the pip download directory between CI runs.
Set generous --timeout and --retries for large dependency sets.
Pin to a reliable index or mirror for your region.