Problem: pip keeps timing out on CN networks — switch to a CN mirror —— Trove problem library

What you will run into

On CN networks (campus/home broadband, no proxy), pip repeatedly times out: ReadTimeoutError: HTTPSConnectionPool(host='download.pytorch.org'...): Read timed out, failing after several retries.

You think it's the package — actually pip downloads from the official source by default, and the official source has no stable acceleration for CN networks — switching sources is far more reliable than waiting out retries.

Why this happens

pip downloads from pypi.org / files.pythonhosted.org by default; these domains have no CN CDN, and direct connections are frequently interfered with or drop packets; big packages like torch go via download.pytorch.org, which is worse.

The official response to such issues is often "internet connection issue because of China" (sd-webui#11785, verbatim).

Behavior varies a lot between networks (campus/home/company), so switching to a CN mirror is the most universal fix.

pip downloads in two stages: "index resolution + artifact distribution". Metadata comes from the index host (pypi.org by default), wheels/sdists from the artifact host (files.pythonhosted.org, redirecting to CDNs per content).

Domestic networks have no stable in-country CDN nodes for these hostnames, so packet loss/resets happen at the transport layer — the error text (timeout/connection reset) has nothing to do with the package.

Mirrors (Tsinghua/Aliyun) mirror both the index and artifact hosting onto domestic nodes: switching the source = switching the resolution entry; package checksums stay identical.

Deterministic takeaway: when pip install stalls, first confirm it is the network layer (curl -I https://pypi.org for the index, download the same wheel directly to test the artifact host), then switch sources;

-i for a one-off vs ~/.pip/pip.conf for persistence behave identically; for large packages (torch), prefer downloading the wheel first then installing locally, to avoid restarting a huge interrupted transfer.

Step by step

1. Confirm it's the source — Required

The host in the error is one of pypi.org / files.pythonhosted.org / download.pytorch.org, and curl https://pypi.org is also slow → it's the source.

2. Switch sources for one install — Required

pip install <pkg> -i https://pypi.tuna.tsinghua.edu.cn/simple

Common mirrors: Tsinghua https://pypi.tuna.tsinghua.edu.cn/simple, Aliyun https://mirrors.aliyun.com/pypi/simple/, Tencent https://mirrors.cloud.tencent.com/pypi/simple.

3. Persist: write it into pip config — Required

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

4. Trusted-host issue (old pip) — Required

Old mirrors reporting untrusted host need --trusted-host pypi.tuna.tsinghua.edu.cn (newer pip doesn't need it).

How to confirm it works

pip download six -i https://pypi.tuna.tsinghua.edu.cn/simple -d /tmp/pip-test

No more timeouts and a successful download means it's fixed (measured: after switching sources, install/download normal; direct official source reproduced ReadTimeoutError).

Other environments

Symptom

pip keeps timing out on domestic networks (campus/home broadband, no proxy):

pip._vendor.urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='download.pytorch.org', port=443): Read timed out.
WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'ReadTimeoutError(...)': /simple/pyyaml/

Key traits: the host in the error is one of pypi.org / files.pythonhosted.org / download.pytorch.org; any package can trigger it, and it fails after a few retries; curl https://pypi.org is likely slow too. Maintainers often answer such issues with "internet connection issue because of China" (verbatim in sd-webui#11785).

Same family but different root cause (don't fight the network on this page):

• Hash mismatch (checksum mismatch after download) -> the mirror is out of sync; switch to another mirror (Aliyun/Tencent) or retry with pip install --no-cache-dir (mechanism-based: mirror cache lag);
• no space left on device (download/install stage) -> disk full; under WSL, df showing free space but writes failing means the host drive is full — check df -h /mnt/c first.

Cause

pip uses the official index by default, which has no stable acceleration for Chinese networks (pypi.org / files.pythonhosted.org have no domestic CDN; direct connections are often interfered with or dropped); torch packages go through download.pytorch.org, which is worse. Network behavior differs greatly: campus, home, and corporate networks perform completely differently, so "switch the index" is more reliable than "wait for retries".

Solution

1. One-off index switch: pip install <pkg> -i https://pypi.tuna.tsinghua.edu.cn/simple (Tsinghua)

or -i https://mirrors.aliyun.com/pypi/simple/ (Aliyun). Both measured under 1s on this campus network.

1. Persistent (recommended): pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple,

written to ~/.config/pip/pip.conf (Linux) / %APPDATA%\pip\pip.ini (Windows); confirm with pip config list; restore with pip config unset global.index-url.

1. torch-specific (same scenario as sd-webui#11785): pip install torch==2.0.1 torchvision==0.15.2 --index-url https://mirrors.aliyun.com/pytorch-wheels/cu118,

change cuXXX to match your CUDA version (cu121/cu124 etc.). Verified: that directory returns HTTP 200 and contains the matching wheels. ⚠️ Tsinghua's pytorch-wheels mirror returns 404 — do not use it.

1. Other usable indexes: Tencent https://mirrors.cloud.tencent.com/pypi/simple;

USTC https://mirrors.ustc.edu.cn/pypi/simple (some old domains are gone).

1. Corporate/offline environments: self-host devpi/nexus and point -i or global.index-url at the internal address.
2. Know the difference between --index-url and --extra-index-url: the official torch command uses --extra-index-url on top of the official index;

when switching to a domestic mirror, use --index-url to fully override, otherwise pip still touches the official index.

Affected Tool Instances

• deepcode (pip install deepcode-hku): large dependency tree (60+ packages incl. aiohttp/cryptography/pillow), mid-download timeouts likely; measured Tsinghua mirror full install 40.3s OK, closed-loop re-verified 2026-08-28.
• code-review-graph (pip install code-review-graph): 159 dependencies (incl. tree-sitter; isolated venv ~326MB); measured Tsinghua mirror venv install OK, v2.3.8.
• logfire (pip install logfire): depends on the opentelemetry family; measured Tsinghua mirror ~15s, v4.41.0; FastAPI integration via logfire[fastapi]. Real telemetry reporting needs a project token + logfire auth login (not tested); Windows/macOS not tested.

Related canonicals

Read as same root (CN mirror family):

• npm install slow/hang (same root: mirror family, node side)
• Go module fetch slow/timeout (same root: mirror family, go side)
• docker pull fails / mirror (same root: mirror family, container side)
• GitHub direct connection slow/fails (same network root: unstable egress, pip vs git)