RUNBOOK / Python / pip
pip install Read timed out：从 DNS 到镜像的系统化排障
安装 requests、torch 或私有依赖时卡在 Read timed out，重试后仍失败。
故障现象与判断依据
最可能原因
先区分解析慢、TLS 握手慢和大文件传输中断；不要先删除虚拟环境。
LOGERROR: Could not install packages due to an OSError:
HTTPSConnectionPool(host='pypi.org', port=443):
Read timed out. (read timeout=15)安全诊断
以下命令用于读取状态、验证解析或复现请求；先确认目标主机、权限与影响范围。命令中的占位符必须替换为当前环境的实际值。
READ / VERIFYpython -m pip install -vvv --timeout 60 --retries 5 <package>
HTTPS_PROXY=http://127.0.0.1:7897 HTTP_PROXY=http://127.0.0.1:7897 curl -Iv --connect-timeout 10 https://pypi.org/simple/推荐修复步骤
- 1在已配置本地 Clash 代理的受控 shell 中执行 pip -vvv install 包名，记录失败主机与阶段。
- 2仅通过已配置的本地代理用 curl -I 测试同一 HTTPS 地址，确认不是 pip 本身的缓存问题。
- 3为单次安装设置 --timeout 60 --retries 5，并选择团队认可的镜像源。
验证、限制与回滚
修复后的验证
再次安装并确认下载速度稳定、哈希校验通过。
风险提示与回滚
不要以关闭证书校验、删除全部缓存、无限重试、关闭防火墙或放宽到 chmod 777 来替代根因定位。任何配置变更前先保留原文件和校验结果；若验证失败，恢复该备份并重新采集日志。
可信来源与适用边界
参考来源Cannot install packages with pip - timeout error · Issue #2409 · pypi/support · GitHub ↗
ReadTimeoutError against pypi.org 此页将环境级案例与本 Runbook 的检查步骤分开呈现，不能把示例日志当作当前服务器的真实事件。
网络环境检测
当 DNS、代理链路、海外依赖源或下载超时已通过本页命令确认是网络层问题时，可继续核对独立网络服务；这不替代本地根因修复。
访问边界云官方网站 →具体套餐、价格、可用线路、服务内容及相关规则以官网当前页面为准；不会携带你在工作台输入的命令、日志、Token、IP 或邮箱。