readtimeouterror主因是pip默认超时仅15秒，非网络故障；解决方法为换国内源（如清华源）并设--default-timeout=120与--retries=5，或永久配置pip.conf。
超时不是网络差，是 pip 默认只肯等 15 秒——换源 + 调 timeout 就能解决 90% 的问题。
为什么 pip install 会卡在 ReadTimeoutError
典型报错是 ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out. (read timeout=15)。这不是 DNS 解析失败，也不是连不上服务器，而是 pip 在接收响应数据流（比如 torch 的 1GB wheel）时，任意一个 TCP 分块停顿超过 15 秒，就直接扔异常。国内访问官方源时，CDN 缓存未命中、运营商中转抖动、TLS 握手延迟都可能触发它。
关键点：--default-timeout 控制的是“单次请求生命周期”，包括 DNS + 连接 + 所有响应读取；它和 --retries 是分开的——默认重试 3 次，每次又都卡满 15 秒才报错，实际等待近 45 秒才失败，但你只看到最后一次的 timeout 提示。
临时生效：命令行加 -i 和 --default-timeout
最安全的调试方式，不改任何配置，适合 CI/CD 或一次性安装大包：
- 用清华源 + 120 秒超时：
pip install torch --default-timeout=120 -i https://pypi.tuna.tsinghua.edu.cn/simple/ - 如果还失败，加
--retries 5增强容错：pip install torch --default-timeout=120 --retries 5 -i https://pypi.tuna.tsinghua.edu.cn/simple/ - 注意：
-i必须写在包名前，否则会被忽略；--default-timeout不能缩写为-t，必须全写
永久配置：改 pip.conf 或设环境变量
长期开发推荐用户级配置，避免每次敲一长串参数：
- Linux/macOS：编辑
~/.pip/pip.conf，加入以下内容：[global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple/ default-timeout = 120 trusted-host = pypi.tuna.tsinghua.edu.cn
- Windows：编辑
%APPDATA%\pip\pip.ini，格式相同 - CI/CD 场景更推荐环境变量：
export PIP_DEFAULT_TIMEOUT=120（bash/zsh）或set PIP_DEFAULT_TIMEOUT=120（cmd） - 别碰系统级配置（如
/etc/pip.conf），容易被其他用户或容器覆盖
超时值设多少才算合理
设太小（如 30）：小包可能成功，但只要中间一次 TCP 重传或 CDN 回源，就失败；设太大（如 600）：真断网时 pip 会傻等 10 分钟才报错，浪费排查时间。
经验阈值：
- 用国内镜像源（清华/阿里/中科大）时，
default-timeout = 60–120足够覆盖绝大多数包（含tensorflow、pytorch） - 若仍超时，大概率不是 timeout 问题，而是本地 DNS 被污染、代理配置冲突、或镜像源本身临时故障（可换
https://mirrors.aliyun.com/pypi/simple/试试） - 永远不要设
timeout=0（无限等待），底层 urllib 不支持，会抛 ValueError
真正难搞的 case 往往藏在细节里：比如公司网络强制走透明代理，但 pip 配了 http_proxy 环境变量，结果双重代理导致 TLS 协商卡死——这种时候调 timeout 没用，得先 unset http_proxy https_proxy 再试。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
