What you see
pip._vendor.urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out.Common causes
- Large wheels, such as machine learning frameworks, downloaded over a slow or congested link.
- Many parallel jobs downloading the same big files at once.
- Flaky connectivity on self-hosted runners.
How to fix it
- 01
Raise the timeout and retries
Helps with short stalls on big files.
shell pip install --timeout 120 --retries 10 -r requirements.txt - 02
Keep pip's cache between runs
Most CI providers can persist ~/.cache/pip keyed on your requirements file.
.github/workflows/ci.yml - uses: actions/setup-python@v5 with: python-version: "3.13" cache: pip - 03
Use a PyPI cache in your region
Big wheels come from the cache at local network speed once they have been pulled once.
shell export PIP_INDEX_URL="https://ci:${CACHEPORT_TOKEN}@acme.cacheport.cc/pypi/simple/"