深夜十一点半CI 流水线卡在最后一步日志窗口里滚动着同一行字Retrying (Retry(total4, connectNone, readNone, redirectNone, statusNone)) after connection broken by ReadTimeoutError。五分钟过去total从 4 降到 0然后报错退出第二天早上重新跑一次又莫名其妙地过了。这种重跑就好、不重跑就废的体验几乎每个写过 Python 包安装脚本的人都遇到过。这篇就来把 Python 包安装里那个最烦人的Retrying拆开看它到底在重试什么、5 种最常见的触发原因分别长什么样、每一种该怎么用参数和配置真正解决掉而不是靠反复重跑来赌运气。无论你是刚学会pip install的新手还是天天维护 CI 流水线的老手下面这套排查顺序和配置模板都可以直接拿去用。1. 从一条卡住的日志说起Retrying 究竟在重试什么1.1 这行字不是 pip 在摆烂是 urllib3 在礼貌地报点很多人看到Retrying的第一反应是pip 又抽风了其实这行字根本不是 pip 自己打印的而是它底层的 HTTP 客户端库在执行重试策略时输出的过程日志。完整的形态通常是这样WARNING: Retrying (Retry(total4, connectNone, readNone, redirectNone, statusNone)) after connection broken by ReadTimeoutError(HTTPSConnectionPool(host..., port443): Read timed out. (read timeout15)): /simple/somepackage/拆开看几个关键信息total4说明还剩 4 次机会默认总共 5 次read timeout15说明这次是读取超时触发阈值是 15 秒最后的/simple/somepackage/是这次请求的路径。这段日志的信息量其实非常大——它同时告诉了你剩余重试次数、失败类型、超时阈值、请求目标。可惜绝大多数人直接把它当成噪声划过去了然后去网上搜pip 安装失败怎么办得到一堆互相矛盾的答案。我自己的习惯是看到Retrying先不要动把这一整段连同下面的Traceback一起复制出来先定位是ReadTimeoutError、ConnectionResetError还是SSLError。这三种对应的处理路径完全不同混着治只会浪费时间。1.2 下载阶段的卡顿和解析阶段的卡顿长得完全不一样一个容易混淆的点pip install其实分成两段完全独立的过程卡在不同位置病因天差地别。第一段是索引查询和元数据获取。pip 会去索引源请求/simple/包名/这个页面拿到所有可用版本列表再逐个下载候选版本的元数据.metadata文件或整个 wheel 的头部来判断依赖关系。这一段的特点是请求次数多、单次数据量小、但极度依赖往返延迟。如果卡在这里你会看到大量针对同一个包名的短请求反复重试。第二段是实际下载与安装。选定版本后pip 去拉完整的 wheel 或源码包这一段单次请求数据量大、耗时长容易撞上读取超时或者连接被中途掐断。区分方法很简单在命令后面加-v日志里会出现Looking in indexes:和Collecting xxx这样的行。如果卡在Collecting之前反复重试是索引查询问题如果Collecting之后开始出现百分比进度然后中断是下载问题。这两类问题的解法在后面的章节里会分别展开。1.3 先学会读那三行关键日志真正需要盯住的其实只有三行日志片段含义指向的排查方向Read timed out. (read timeout15)连接建立了但数据迟迟不来超时阈值太小、链路抖动、包太大ConnectionResetError(104)/Connection aborted连接被对端或中间设备掐断出口网关空闲连接回收、镜像站限流SSLError(...CERTIFICATE_VERIFY_FAILED...)证书校验没过系统时间、CA 证书包、内网自签证书Could not find a version that satisfies the requirement索引里确实没有这个版本源不对、版本号写错、包被撤下把这张表记住你已经能在 30 秒内判断出该往哪个方向查了。剩下四节就是逐条把每种原因讲到能落地操作的程度。2. 原因一timeout 和 retries 在最不该省的地方被默认值绑住了2.1 15 秒 × 5 次背后的时间账pip 的--timeout默认值是 15 秒--retries默认值是 5 次。这个组合在十年前的网络环境下是合理的放到今天就是灾难——尤其是在拉取体积几十兆甚至上百兆的 wheel 包时。算一笔账一次下载如果稳定速度只有 200KB/s一个 40MB 的包需要 200 秒而读取超时的判定是连续 15 秒没有收到任何数据。只要中间有一段网络抖动导致数据停顿超过 15 秒这次下载就作废从头再来。5 次重试全部失败的概率在跨地域链路上其实相当高。更麻烦的是重试是从头开始的没有断点续传的保证。所以你会看到进度条走到 70% 突然归零重来反复几次之后报错。用户感知就是pip 一直在 Retrying实际上每一次重试都真的在下载只是每次都功亏一篑。提示把超时理解成数据停顿容忍时间而不是总下载时间很多困惑就解开了。一个 500MB 的包正常下载 20 分钟完全没问题只要中间不出现连续 15 秒的空窗。2.2 参数该落在哪一层命令行、环境变量还是配置文件调这两个参数有三个落点优先级从高到低是命令行、环境变量、配置文件。临时排查用命令行长期生效走配置文件CI 环境里用环境变量最方便# 临时单次生效 pip install somepackage --timeout 60 --retries 10 # 环境变量CI 里最常用 export PIP_DEFAULT_TIMEOUT60 export PIP_RETRIES10 # 配置文件里写死 pip config set global.timeout 60 pip config set global.retries 10具体调成多少我一般的经验值是普通开发机 60 秒超时 / 10 次重试CI 环境 30 秒超时 / 3 次重试。方向是反的原因是 CI 环境最怕的不是失败而是慢——一个卡住 15 分钟的构建比一个 2 分钟就失败退出的构建糟糕得多。CI 里重试次数少一点快速失败把重试交给流水线本身去做反而更划算。2.3 大包和 CI 应该用完全不同的策略对于已知体积大的包带完整运行时的那类单独给它一套参数更省心。可以先把包下载到本地再离线安装这样即使后面安装环节出问题也不用重新下载pip download somepackage -d ./wheels --timeout 120 --retries 20 pip install --no-index --find-links ./wheels somepackage--no-index加--find-links这个组合是我在弱网环境里的常用招数彻底跳过索引查询阶段所有包都从本地目录找把网络依赖压到最低。顺带一个小技巧pip download出来的 wheel 可以塞进构建缓存下次构建的命中率会高很多。3. 原因二索引源配置的层层叠加与互相打架3.1 一条 pip config list 能省下两个小时我见过太多pip 行为诡异的案例最后发现是配置文件里躺着一行半年前加的index-url。诊断第一步永远是pip config list pip config debugpip config list输出的是当前实际生效的所有配置项pip config debug会额外告诉你它读了哪些文件、每个文件是否存在。这两条命令加起来不到两秒但能直接排除掉一大半玄学问题。有一次某位同学反馈说他本地怎么都装不上某个包跑完pip config debug发现配置文件里写的是一个早就下线的内网地址他自己完全不记得改过。3.2 四个配置层级和它们的覆盖顺序pip 的配置不是只有一份而是四个层级依次叠加后读的覆盖先读的层级Linux / macOS 位置Windows 位置说明全局/etc/pip.confC:\ProgramData\pip\pip.ini系统级装了多个 Python 都会读到用户~/.config/pip/pip.conf%APPDATA%\pip\pip.ini最常见pip config set默认写这里虚拟环境$VIRTUAL_ENV/pip.conf%VIRTUAL_ENV%\pip.ini只在这个 venv 里生效优先级最高环境变量PIP_*PIP_*覆盖上面所有文件这个顺序解释了很多为什么我在 A 环境能装、B 环境不能装的问题——两边读到的配置文件根本不是同一份。虚拟环境那一层特别值得利用给某个项目单独放一份pip.conf在 venv 目录下就能做到项目级的源隔离不污染全局。3.3 extra-index-url 的隐性代价--extra-index-url看着很美主源加一个补充源两边都能找。但它的实现方式是同时向所有索引源发请求然后把结果合并。这意味着每个包的查询开销直接翻倍在往返延迟高的链路上感知上就是变慢了一倍。更隐蔽的坑是如果两个源里存在同名但内容不同的包pip 会按版本号选择你可能装到一个不是你以为的那个。我在内部项目里见过因为这个问题引入了来源不明的同版本包排查了大半天。我的建议很明确能用单一源解决的问题就不要用 extra-index-url。确实需要多源时明确指定哪个包从哪个源来pip install somepackage --index-url https://mirrors.example.internal/simple pip install otherpackage --index-url https://pypi.example.org/simple多写几行命令换来的是行为可预期。这笔买卖划算。4. 原因三证书校验失败被伪装成了网络超时4.1 CERTIFICATE_VERIFY_FAILED 的三种常见面孔证书问题最坑的地方在于它有时候并不会老老实实报出SSLError而是表现为握手阶段反复超时最后给你一个Retrying加ReadTimeoutError。真正的原因藏在更上面几行日志里。三种典型场景系统时间不对。虚拟机快照恢复、容器镜像时间戳异常都会让系统时间偏离真实时间。证书有生效区间时间不对直接校验失败报错里会出现certificate is not yet valid或certificate has expired。CA 证书包过旧。certifi这个包就是专门管证书的版本太老会导致新的根证书不被认识。内网源使用自签证书。公司自建的镜像服务用内部 CA 签的证书本机没有把这个 CA 加进信任链。排查顺序建议先date看一眼时间对不对一秒钟的事但能解决相当比例的问题。然后升级certifipython -m pip install --upgrade certifi python -c import certifi; print(certifi.where())第二条命令会打印出当前使用的证书包路径对于排查到底读的是哪个证书包非常有用。4.2 让 pip 认识你的内部 CA如果是内网自签证书正确的做法是把内部 CA 证书导入信任链而不是直接关掉校验。有两种做法# 方式一通过环境变量指定额外的 CA 包 export PIP_CERT/path/to/internal-ca-bundle.pem # 方式二直接把 CA 追加到 certifi 的包里注意升级 certifi 后要重做 cat internal-ca.crt $(python -c import certifi; print(certifi.where()))方式一更干净推荐优先用。4.3 trusted-host 的边界在哪里--trusted-host这个参数很多人当万能药在用一遇到证书问题就加上去。它确实能绕过校验让安装继续但代价是这个域名下的所有内容都不再验证来源。在受控的内网环境里为了效率这么做可以接受在公网环境里这是在拿依赖安全换便利。我的底线是trusted-host只写内网镜像的具体域名绝不写通配也绝不在公网源上用它。配置写成这样[global] index-url https://mirrors.example.internal/simple trusted-host mirrors.example.internal域名写死范围可控。真出了事至少知道影响面在哪里。5. 原因四DNS 解析与 IPv6 优先级带来的首包黑洞5.1 解析慢和连接慢症状很像但根因不同Retrying还有一种容易被误判的成因DNS 解析阶段就卡住了。表现是 pip 启动之后长时间没有任何输出然后突然开始刷重试。这时候看超时日志会发现connect timeout而不是read timeout——注意区分这两个词connect是连都连不上read是连上了但拿不到数据。验证方法很直接# 看域名解析耗时 time getent hosts mirrors.example.internal # 更细致的解析过程 dig stats mirrors.example.internal如果解析本身就花了好几秒问题就不在 pip 而在 DNS。常见原因是配置了多个 DNS 服务器第一个不响应要等超时才轮询到第二个。5.2 IPv6 优先策略在只有 IPv4 出口时的表现这是一个非常经典的坑系统默认优先使用 IPv6但实际网络环境只有 IPv4 出口或者 IPv6 路由不通。表现就是每次连接都先尝试 IPv6等超时通常几秒到几十秒再回落到 IPv4。单个请求看不出来但 pip 一次安装要发几十上百个请求累积起来就是灾难级的慢。判断方法# 强制走 IPv4 试试如果速度立刻正常基本就确认了 pip install somepackage --timeout 30 -v 21 | head -50如果确认是这个原因可以在系统层面调整地址优先级/etc/gai.conf里把 IPv4 的优先级调高或者在容器/CI 环境里直接禁用 IPv6。这属于系统配置层面的处理改完对所有命令行工具都生效比在 pip 上打补丁更彻底。5.3 三条能立刻验证的命令遇到卡在连接阶段的情况我会按这个顺序敲三条命令通常两分钟内能定性# 1. 通不通 ping -c 4 mirrors.example.internal # 2. 端口通不通443 是否可达 curl -v --max-time 10 https://mirrors.example.internal/simple/ -o /dev/null # 3. HTTP 层面通不通不带 TLS看是否有中间拦截 curl -v --max-time 10 http://mirrors.example.internal/simple/ -o /dev/null第二条命令的-v输出里会明确写出 DNS 解析耗时、TCP 连接耗时、TLS 握手耗时这三段哪一段慢一目了然。这比盲猜高效太多了我现在基本不再用别的工具做这个判断。6. 原因五看着像网络问题其实是包和元数据在作怪6.1 版本根本不存在时pip 会把所有源翻个遍有一类重试其实和网络质量毫无关系。当你写了一个不存在的版本号比如把2.1.0写成了2.1.0.0pip 不会立刻告诉你没有这个版本而是会去索引里把所有版本列表拉一遍尝试各种匹配最后才报Could not find a version that satisfies the requirement。在源响应慢的情况下这个过程本身就会产生大量重试日志让你误以为是网络问题。快速确认的办法是先看有哪些版本可用pip index versions somepackage如果这条命令本身也报错或超时那确实是源的问题如果它能正常列出所有版本那问题就在你写的版本号上。另外注意--pre参数不加上它预发布版本是不会被选中的有些人写了个 beta 版本号却忘了加--pre然后对着找不到版本的报错发呆。6.2 需要本地编译时的长时间假死安装某些包含 C 扩展的包时如果索引里没有匹配当前平台和 Python 版本的预编译 wheelpip 会退回到源码包自己编译。这个过程的日志会长时间停住不动看起来就像卡死了。判断是不是这个情况看日志里有没有出现Building wheel for xxx或者Running setup.py install。如果有那它其实在正常工作只是慢。避免它的办法有两个。一是优先选预编译包pip install somepackage --only-binary :all:这条命令的意思是只接受预编译包装不上就报错。听起来很严格但好处是快速失败——你会立刻知道当前平台没有现成的 wheel而不是等二十分钟编译完才发现缺了编译工具链。确认确实需要编译时再去掉这个参数。另一个是检查当前环境支持的 wheel 标签确认是不是环境本身太特殊比如很新的 Python 版本、非主流架构pip debug --verbose输出里的Compatible tags列表会列全当前环境能接受的所有 wheel 标签。对着这个列表去看某个包提供了哪些标签匹配不上就是匹配不上别硬等。6.3 依赖解析回溯pip 自己的另一种重试还有一类耗时发生在依赖解析阶段日志里会出现Collecting和Downloading交替然后突然开始回溯——pip 发现版本组合冲突回退到更早的候选版本重新尝试。依赖树复杂的时候这个过程可能尝试几十上百种组合表现出来的就是安装特别慢还一直重复下载同样的包。这个问题在较新的 pip 版本里改善了很多所以第一条建议永远是升级 pip 本身python -m pip install --upgrade pip如果升级后依然慢可以先用--no-deps只装主包再单独处理依赖把问题范围缩小pip install somepackage --no-deps -v顺带说一句用python -m pip而不是直接敲pip能避免多环境下的解释器错配——这个习惯我建议所有人在一开始就养成。7. 我自己的排查顺序从三分钟定位到十分钟解决7.1 一张按成本排序的排查表真遇到问题的时候按成本从低到高逐条排除比上来就改配置高效得多顺序动作耗时能排除的问题1pip config listpip config debug2 秒源配置错误、残留配置2date看系统时间1 秒证书有效期校验失败3curl -v --max-time 10 源地址10 秒DNS、连通性、TLS 握手4加-v重跑看是 connect 还是 read 超时1 分钟连接问题 vs 下载问题5pip index versions 包名10 秒版本号写错、包不存在6--only-binary :all:试一次30 秒无预编译包导致的编译等待7pip cache purge后重试1 分钟缓存损坏8调--timeout和--retries1 分钟链路抖动、大包传输注意第 7 条那个缓存问题。pip cache purge平时没人想起来但缓存文件损坏确实会导致反复下载同一个包然后校验失败。缓存的默认位置Linux 在~/.cache/pipmacOS 在~/Library/Caches/pipWindows 在%LocalAppData%\pip\Cache。用pip cache dir可以直接问出来用pip cache info能看到占用多少空间。磁盘满的时候 pip 的报错也是千奇百怪顺手看一眼磁盘剩余空间不会错。7.2 一份可以直接抄的配置模板把我这几年稳定用下来的一套配置贴出来按自己的镜像地址替换域名即可[global] index-url https://mirrors.example.internal/simple trusted-host mirrors.example.internal timeout 60 retries 10 disable-pip-version-check true [install] prefer-binary true几个字段的用意解释一下。prefer-binary让它优先挑预编译包能绕开大量编译等待。disable-pip-version-check关掉那个烦人的升级提示同时少一次额外的网络请求——在 CI 里这个请求偶尔也会卡。timeout和retries按前面第 2 节的经验值来。写进配置文件有两种方式直接编辑对应路径的文件或者用pip config set命令。后者更安全因为它会写到正确的用户级路径下不会因为你记错路径而写了个永远不会被读到的文件。虚拟环境里想单独覆盖就在$VIRTUAL_ENV/pip.conf里放一份精简版只写要覆盖的那几项。7.3 CI 环境里那几条容易踩的额外注意事项CI 和本地开发机的排查思路要分开。CI 里我踩过的几个坑列出来省得别人再踩第一构建机没有持久化缓存。每次构建都从零下载全部依赖命中不了任何缓存。解决办法是在流水线里显式缓存pip cache dir返回的目录key 用requirements.txt的哈希值这样依赖没变就能直接复用。第二构建机的时间和时区。容器镜像的时间戳偶尔会漂导致证书校验失败而报错信息又指向网络超时。在流水线开头加一行打印时间的命令能省掉大量排查时间。第三不要在 CI 里用--trusted-host兜底。本地为了图快加上的参数一旦进了 CI 配置就会一直留着几个月后没人知道它为什么在那儿。如果确实需要写在 CI 专用的配置文件里并加注释说明原因。第四给安装步骤设置整体超时。pip自己的重心放在单次请求上整个安装过程可能因为依赖解析而耗时极长。流水线层面加一个总时长限制超时直接失败比卡在那里占着构建机划算得多。最后分享一个小习惯我习惯在项目根目录留一个scripts/install.sh把pip install -r requirements.txt加上常用的--timeout、--retries、--prefer-binary全部封装进去。团队里新人不看文档也能跑对参数也不会因为某个人本地配了个奇怪的源而装出不一样的结果。这种把正确做法固化成脚本的思路比在群里反复解释你要加个参数有效得多——踩过的坑最好让它只被踩一次。
