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.

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.

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

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.

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

Use a closer or internal mirror

1. Point pip at a geographically closer mirror or a pull-through cache.
2. Host an internal index (devpi, Artifactory) for high-volume pipelines.
3. 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

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation