pip 安装超时/下载慢（ReadTimeoutError / WARNING: Retrying ... Read timed out）

你会遇到什么

国内网络（校园网/家庭宽带，无代理）跑 pip 时反复超时：ReadTimeoutError: HTTPSConnectionPool(host='download.pytorch.org'...): Read timed out，重试几轮后失败。你以为是包的问题，其实是pip 默认从官方源下载，而官方源对国内网络没有稳定加速——换源比等重试可靠得多。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

pip 默认从 pypi.org / files.pythonhosted.org 下载，这些域名对国内网络没有国内 CDN，直连经常被干扰或丢包；torch 类大包走 download.pytorch.org，情况更糟。官方对这类 issue 的回复往往是「internet connection issue because of China」（sd-webui#11785 原话）。

同族但根因不同（别在本页死磕网络）：

• Hash mismatch（下载后校验和不符）→ 镜像站同步延迟，换另一个镜像（阿里/腾讯）或 pip install --no-cache-dir 重试（机制核对：镜像缓存不同步）；
• no space left on device（下载/安装阶段）→ 磁盘满；WSL 下 df 有空间但写不进是宿主盘满，先查 df -h /mnt/c。不同网络（校园网/家宽/公司）表现差异很大，所以换国内镜像源是最通用的解法。

实测环境：校园网无代理，2026-08-29。

pip 的下载是「index 寻址 + 文件分发」两段：元数据从 index 域名（默认 pypi.org）拉，wheel/sdist 从文件托管域名（files.pythonhosted.org，按内容重定向到 CDN）拉。国内网络对这两个域名没有稳定的国内 CDN 节点，丢包/重置发生在传输层——报错文案（timeout/connection reset）与包无关。

镜像源（清华/阿里）是把 index 和文件托管一起镜像到国内节点，换源 = 换寻址入口，包的校验和不变。

确定性推论：pip install 卡住先确认是网络层（curl -I https://pypi.org 测 index、直接下同一个 wheel 测文件域名），再换源；-i 临时换源 vs 写进 ~/.pip/pip.conf 持久换源效果相同；大包（torch）优先下载 wheel 文件再本地装，避免大文件传输中断重来。

一步步来

1. 确认是源的问题 — 必做

报错里的 host 是 pypi.org / files.pythonhosted.org / download.pytorch.org 之一，且 curl https://pypi.org 也慢 → 就是源的问题。

2. 临时换源装一次 — 必做

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

常用镜像：清华 https://pypi.tuna.tsinghua.edu.cn/simple、阿里 https://mirrors.aliyun.com/pypi/simple/、腾讯 https://mirrors.cloud.tencent.com/pypi/simple。

3. 长期生效：写进 pip 配置 — 必做

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

4. 信任主机问题（旧版 pip） — 必做

老镜像报 untrusted host 时补 --trusted-host pypi.tuna.tsinghua.edu.cn（新版已不需要）。

怎么确认修好了

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

不再报超时、能正常下载即成功（实测：换源后安装/下载正常；官方源直连则 ReadTimeoutError 复现）。

其它环境的表现

症状

国内网络（校园网/家庭宽带，无代理）跑 pip 时反复超时：

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/

特征：报错里的 host 是 pypi.org/files.pythonhosted.org/download.pytorch.org 之一； 装任何包都可能触发，重试几轮后失败；curl https://pypi.org 大概率也慢。 官方对这类 issue 的回复往往是「internet connection issue because of China」（sd-webui#11785 原话）。

原因

pip 默认从官方源下载，而官方源对国内网络没有稳定加速（pypi.org / files.pythonhosted.org 无国内 CDN， 直连经常被干扰或丢包）；torch 类包走 download.pytorch.org，情况更糟。 同一时间不同网络差异很大：校园网、家宽、公司网表现完全不同，所以「换源」比「等重试」可靠。

解法

1. 一次性换源：pip install <包> -i https://pypi.tuna.tsinghua.edu.cn/simple
2. 长期生效：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
3. 旧版 pip 补 --trusted-host；大包优先换源再装。

相关 canonical

按「同根（国内换源家族）」读：

• npm install 慢/挂起（同根：换源家族，node 侧）
• Go 模块拉取慢/超时（同根：换源家族，go 侧）
• docker pull 失败/镜像加速（同根：换源家族，容器侧）
• GitHub 直连慢/失败（网络层同根：出口不稳，一为 pip 一为 git）