cacheport

Error · pip

Fixing pip ReadTimeoutError on files.pythonhosted.org

pip connected to PyPI's file host and started downloading, but the data stopped arriving for longer than pip's timeout, 15 seconds by default. pip gives up on that file and the install fails.

What you see

build log
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

  1. 01

    Raise the timeout and retries

    Helps with short stalls on big files.

    shell
    pip install --timeout 120 --retries 10 -r requirements.txt
  2. 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
  3. 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/"

Other network failures in builds

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.