pip install 超时 Read timed out 报错怎么解决

在使用 Python 的包管理器执行 pip install 安装第三方库时，终端若突然中断并输出类似 pip._vendor.urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(...) Read timed out. 的红色报错，其根本原因是 pip 客户端在建立网络连接后，等待官方源服务器返回数据流的时间超过了内部设定的超时阈值。解决该问题的核心路径十分明确：在紧急情况下通过参数延长超时限制或单次指定国内镜像源；而在日常开发中，通过命令写入全局国内镜像源配置即可一劳永逸地解决超时问题。

一、报错表现与根本原因剖析

典型的错误日志通常如下所示，在下载进度条走到一半或者刚刚解析完依赖版本时直接抛出异常：

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'ReadTimeoutError("HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out. (read timeout=15)")': /packages/...
ERROR: Exception:
Traceback (most recent call last):
  ...
pip._vendor.urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out.

这一现象主要由以下三个技术因素叠加导致：

• 默认超时时间偏短：早期版本的 pip 默认读取超时时间仅为 15 秒（较新版本虽调整至更高，但面对百兆文件依然脆弱）。一旦某一段数据在规定时间内未送达客户端缓冲区，连接即被主动终止。
• 官方源地理位置限制：Python 官方源（PyPI 位于国外服务器）的链路跳数多、跨洋带宽受限，常遭遇高延迟与偶发性丢包。
• 依赖包体积较大：如 PyTorch、TensorFlow、Pandas、scipy 或带 C 扩展编译的 wheel 二进制包，体积从几十兆到上百兆不等，在网络轻微抖动时极易突破超时上限。

二、紧急临时处理：单次命令解决超时

如果当前仅需要临时安装某一个库，或者在临时测试环境、CI/CD 自动化流水线脚本中运行，可以使用命令行参数即时调整，无需修改全局配置文件。

方法 1：使用 --default-timeout 延长等待上限

通过添加 --default-timeout 参数，显式将等待服务端发送数据包的超时阈值设定为 100 秒或更久（单位为秒）：

# 将超时时间延长为 100 秒
pip --default-timeout=100 install requests

# 面对特大体积依赖包，可延长至 600 秒
pip --default-timeout=600 install scipy

注意：该参数必须跟随在 pip 之后或 install 之后均可，例如 pip install --default-timeout=100 <package>。

方法 2：单次指定国内镜像源（推荐）

仅延长等待时间仍可能因跨国链路中断而失败，直接换用国内 CDN 镜像站是更彻底的解决方案。使用 -i 或 --index-url 参数：

# 使用清华大学开源软件镜像站安装
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# 使用阿里云开源镜像站安装
pip install pandas -i https://mirrors.aliyun.com/pypi/simple/

方法 3：双管齐下（超时参数 + 镜像源 + 信任主机）

如果所在网络较为恶劣，或者内网环境下存在 SSL 证书拦截，可以组合使用超时扩展、国内镜像及免验安全域名的参数：

pip --default-timeout=120 install torch -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

三、一劳永逸：配置永久国内镜像源

每次手动在命令后拼接 -i https://... 极其繁琐，且容易在 requirements.txt 安装或通过脚本执行时遗漏。最规范的解决方式是在操作系统中配置全局镜像源。

1. 使用现代 pip 命令行自动化写入（推荐）

pip 10.0 及以上版本内置了 config 命令，无需手动寻找配置文件的存储目录，直接在终端中运行以下命令即可：

# 设置清华镜像源为全局默认源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 设置额外的备用源（可选，防止单一镜像站维护）
pip config set global.extra-index-url https://mirrors.aliyun.com/pypi/simple/

# 同时将默认超时时间固化为 100 秒
pip config set global.timeout 100

执行完成后，可运行以下命令验证已生效的配置参数：

pip config list

终端应返回如下清晰键值：

global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
global.extra-index-url='https://mirrors.aliyun.com/pypi/simple/'
global.timeout='100'

2. 手动创建或编辑配置文件

如果所在机器权限受限或需要直接分发配置文件，可以直接在各操作系统的对应位置创建纯文本文件：

3. 国内常用高可靠镜像源地址列表

国内各大高校和头部科技企业均提供了完全免费的 PyPI 镜像站服务，可按所在网络服务商选择延迟最低的镜像：

四、进阶排查：换源后依旧 Read timed out 的特殊场景

少数情况下，读者在更换了国内源后仍旧出现 Read timed out，此时问题通常不再是跨国网络问题，而是系统级网络配置引发的冲突：

1. 终端残留系统代理或 VPN 环境变量

许多开发者开启了网络代理软件，代理工具常常会在系统的终端环境变量中注入 http_proxy 或 https_proxy。当 pip 访问国内镜像站（如清华源）时，请求却被强制转发给本地代理端口，造成“国内站点绕道代理导致超时断开”。

排查与临时清空命令：

# Linux / macOS 临时注销代理环境变量
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY

# Windows PowerShell 临时注销代理环境变量
$env:http_proxy=""
$env:https_proxy=""

# Windows CMD 临时注销
set http_proxy=
set https_proxy=

2. 企业内网 SSL 劫持导致握手超时

部分企业或学校内网部署了中间人安全审计网关，导致 pip 在校验 SSL 证书时阻塞并最终超时。若确认网络环境受控，可使用 --trusted-host 跳过证书信任检查：

pip install <package_name> -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

3. 本地损坏的 wheel 缓存文件

如果此前某次下载在 99% 时断开，pip 本地缓存目录中可能残留损坏的分片文件，后续执行时反复读取残损文件可能诱发死锁或再次超时。此时可强制跳过缓存：

# 忽略本地下载缓存，重新拉取全新包数据流
pip install --no-cache-dir requests

五、策略选型与决策总结

针对不同的使用场景，选择正确的处理手段可以节省排查时间：