pip超时失败主因是默认timeout仅15秒，调高default-timeout（推荐60–120）可解决；支持命令行--default-timeout、配置文件或PIP_DEFAULT_TIMEOUT环境变量三种方式设置。
pip install 超时失败，根本不是网络差，而是默认 timeout 太短（仅 15 秒），改 default-timeout 就能解决。
为什么 pip 会报 timeout 错误而不是连接失败
pip 默认用的是 urllib 的底层 HTTP 请求，default-timeout 控制整个请求生命周期（DNS 解析 + 连接 + 响应读取）。国内源虽快，但某些包（如 torch、tensorflow）体积大、分块多，单次响应可能卡在某个 chunk 上，15 秒一到直接抛 ReadTimeoutError 或 ConnectionError。
- 典型错误信息：
ReadTimeoutError: HTTPSConnectionPool(host='pypi.org', port=443): Read timed out. (read timeout=15) - 不是
pip config list显示的配置项，它不走全局 config，得手动指定或写入配置文件 - 命令行传参优先级高于配置文件，适合临时调试
三种改 timeout 的方法及适用场景
按推荐顺序排列，兼顾安全性和易用性：
- 临时生效（单次安装）：加
--default-timeout=100参数，比如pip install torch --default-timeout=100 -i https://pypi.tuna.tsinghua.edu.cn/simple/ - 用户级持久配置（推荐）：编辑
pip.conf（Linux/macOS）或pip.ini（Windows），在[global]下加一行default-timeout = 100；路径分别是~/.pip/pip.conf和%APPDATA%\pip\pip.ini - 环境变量方式（CI/CD 友好）：设
PIP_DEFAULT_TIMEOUT=100，bash/zsh 中用export PIP_DEFAULT_TIMEOUT=100，Windows cmd 用set PIP_DEFAULT_TIMEOUT=100
timeout 设太大或太小分别有什么问题
这个值不是越大越好，也不是越小越“高效”：
立即学习“Python免费学习笔记（深入）”；
- 设太小（如
5）：小包可能成功，但只要中间有任意一次 TCP 包重传或 CDN 缓存未命中，就大概率失败 - 设太大（如
600）：遇到真断网或源彻底不可达时，pip 会傻等 10 分钟才报错，拖慢排查节奏 - 经验建议值：国内镜像源下设
60–120足够；若还失败，大概率是源本身异常或本地 DNS/代理问题，不是 timeout 的锅 - 注意：该参数不影响下载速度，只影响“愿意等多久”，和
--retries是正交的——后者控制失败后重试次数，前者控制每次尝试最长忍耐时间
真正卡住的时候，往往不是 timeout 数值没调对，而是 pip 正在默默重试三次，每次又都超时，最后才报错。所以看到超时提示，先确认是不是重试耗尽了，再决定调 timeout 还是换源或关代理。
