pip "ReadTimeoutError" / Connection Timeouts in CI

By Kaveh Alemi·Latchkey

pip’s connection to the index stalled or dropped mid-download. These are transient network failures and almost always succeed on retry.

What this error means

pip fails partway through fetching a package with a read timeout or a broken connection. Re-running the job usually works with no change - the hallmark of a transient network issue.

pip output

WARNING: Retrying (Retry(total=2, ...)) after connection broken by
'ReadTimeoutError("HTTPSConnectionPool(host='files.pythonhosted.org', port=443):
Read timed out. (read timeout=15)")'
ERROR: Could not install packages due to an OSError: ... Read timed out.

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.

Terminal

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 network or mirror slowness

A brief connectivity blip or an overloaded PyPI mirror causes the download to exceed pip’s default timeout. Nothing is wrong with your project.

Large wheels over a slow link

Big binary wheels (PyTorch, scientific stacks) can exceed the default 15s read timeout on a congested runner network.

How to fix it

Raise the timeout and retries

Terminal

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

Cache the pip download cache

Caching ~/.cache/pip between runs means most wheels are already local, so a flaky network matters far less.

.github/workflows/ci.yml

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

Use a closer or internal mirror

Point pip at a geographically closer mirror or a pull-through cache.
Host an internal index (devpi, Artifactory) for high-volume pipelines.
Pin a lockfile so the set of downloads is stable and cacheable.

How to prevent it

Cache the pip cache keyed on the lockfile.
Raise PIP_DEFAULT_TIMEOUT for pipelines that pull large wheels.
Use an internal mirror to reduce dependence on public PyPI.

Frequently asked questions

What causes pip "ReadTimeoutError" / connection timeouts in CI?

There are 2 common causes: transient network or mirror slowness and large wheels over a slow link. A brief connectivity blip or an overloaded PyPI mirror causes the download to exceed pip’s default timeout.

How do I fix pip "ReadTimeoutError" / connection timeouts in CI?

There are 3 fixes depending on which cause you have: raise the timeout and retries, cache the pip download cache, and use a closer or internal mirror. Work through them in order, since the first is the most common.

What does pip "ReadTimeoutError" / connection timeouts in CI actually mean?

pip fails partway through fetching a package with a read timeout or a broken connection.

How do I stop pip "ReadTimeoutError" / connection timeouts in CI happening again?

Cache the pip cache keyed on the lockfile. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.