pip安装太慢怎么换源?三类镜像与超时参数
- 2026年11月22日
- 14 次
上周四流水线在装依赖那一步停住了。一个只依赖 requests 和 httpx 的镜像,41 MB、23 个包,跑到十四分钟还没结束,被 CI 的十五分钟上限掐断。翻日志不像断网,是默认往 pypi.org 拉包,速度掉到五十 KB/s 上下。原因不在带宽,是索引源和超时没配上,pip安装太慢只是它露出来的一面。换到清华源、把超时和重试写死,同一条构建两分四十秒出了镜像。
换源落在三个位置
换源没有插件可装,本质就是把 pip 请求的索引地址换掉。它有三个落点,优先级从高到低:命令行 -i、环境变量 PIP_INDEX_URL、配置文件里的 global.index-url。临时验证某个包用命令行,容器构建用环境变量,本机长期用配置文件。

配置文件在各平台的路径不一样:Linux 是 ~/.config/pip/pip.conf,macOS 是 ~/Library/Application Support/pip/pip.conf,Windows 是 %APPDATA%\pip\pip.ini。手改容易改到另一个解释器读的那份,用 pip 自己的子命令更稳。
第一步把源写进去,第二步读回来确认。命令写 pip 还是 python -m pip,看机器上装了几个解释器,多版本并存时后者更保险。
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config list
第二条命令会回一行 global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple',等号右边带单引号。输出是空的,说明写进了另一个 Python 环境,python -m pip config debug 会列出它实际读到的每一个文件。
优先级值得记一下:命令行盖过环境变量,环境变量盖过配置文件。有人在 CI 里设了 PIP_INDEX_URL,本机又改了配置文件,两边指的不是一个源,排查时容易绕圈。
三类镜像源的响应差别
三类源要分开看:官方 pypi.org、国内公共镜像、团队自建的私有源。差别不在绝对速度,在同步延迟、包完整度和出口带宽上。
官方源是唯一没有同步延迟的,包一发布就在上面;代价是跨境链路,晚高峰单连接几十 KB/s。国内公共镜像(清华 TUNA、阿里云、中科大)整站同步,通常几分钟到半小时的延迟,出口在国内,同样的 41 MB 一分钟出头能拉完。私有源(Nexus、devpi)只缓存团队装过的包,命中时最快,没缓存过就要回源,第一次装反而比公共镜像慢。选错源,装包会从偶发变每天。

链路上是这样串的:pip 先向 index-url 要索引页,镜像命中就直接给文件地址,没命中就回源到 pypi.org 拉一次并缓存。
判断某个镜像新不新,看镜像首页标的同步时间,或者用 pip index versions <包名> 跟官方页面对一下版本号,比凭印象猜靠谱。
所以发版当天走镜像可能比走官方还慢半拍,它得先回源。等同步跑完,速度才回来。
超时与重试参数怎么定
pip 的默认 --timeout 是 15 秒,--retries 是 5 次。这套默认值在跨境链路上不够用。超时时终端会打 Read timed out. (read timeout=15),前面还挂着 urllib3 的计数 Retry(total=4, ...):看到 15 就是默认值在起作用,看到 4 说明这是五次里的第二次。
我把 --timeout 提到 60,--retries 压到 3。这两个数得一起改才说得通。默认值的问题不是总时长,是判得太早:跨境链路晚高峰单次读常在 20 到 40 秒之间,15 秒一到就判超时,五次全判死,包一个字节没落盘。抬到 60 是让真在传的连接传完,压到 3 是让彻底不通的源尽快落败。单看最坏值 3×60=180 秒确实比默认的 5×15=75 秒长,可 23 个包全挂就是 69 分钟,这个数字正好说明参数救不了大面积断流——那是换源的事。源换对了仍然慢,问题基本都在这两个数上。
补一句容易搞错的:--timeout 管的是单次读的超时,不是整个包的下载总时长。41 MB 在五十 KB/s 下慢慢拖十几分钟,它不会因为总耗时被打断;但传输中途卡住超过阈值,那一次读照样断。连接建立那一步另算,那是 connect 超时,和这个参数不是一回事。

参数直接挂在命令后面,不动全局变量。
python -m pip install -r requirements.txt --timeout 60 --retries 3
跑完最后一行以 Successfully installed 开头,后面跟一串「包名-版本号」。要是长时间停在 Building wheel for ...,那就不是下载的事,pip安装太慢的原因已经不在网络这一侧了。
这条路径的价值在于失败得快:源不通时三次重试跑完就报错,而不是耗到流水线自己超时,报错只剩一行 timeout。
换完怎么确认走对了源
确认走没走对源,加个 -v 装一个小包就够:python -m pip install -v requests。
输出里有一段 Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple。这个地址由 pip 自己报出来,比翻配置文件可靠。还是 pypi.org,就按命令行、环境变量、配置文件的顺序往下查一层。
什么时候换源解决不了
前面讲的是下载慢,下面这几种情况,换源也解决不了pip安装太慢。包不在镜像上,是第一种:刚发布几小时的版本、被 yank 的版本、公司内部包,公共镜像要么没有要么还是旧的,pip 报 Could not find a version that satisfies the requirement。能等就等同步,等不了就把 --index-url 临时指回官方。
私有源只开 HTTP,是第二种。pip 打一行 is not a trusted or secure host and is being ignored 就直接跳过这个源,得显式给信任:
python -m pip install -r requirements.txt \
--index-url http://nexus.internal/repository/pypi/simple \
--trusted-host nexus.internal
--trusted-host 写主机名,或者主机名加端口,别带 /repository/... 这种路径。
第三种对应的是编译慢:包只有源码包、没有对应平台的 wheel,pip 得现场编译。日志长时间停在 Building wheel for ...,CPU 跑满,网络和磁盘几乎是空的。换成哪个镜像都一样慢,该做的是找预编译的 wheel,或者把编译依赖打进基础镜像。
这笔账算得清:改一行索引、加两个参数,前后不到十分钟,流水线从十四分钟回到两分多钟。下次再碰上pip安装太慢,我先看 pip config list 那一行,把源钉死,再谈超时。
若非作者标注皆为李涛自留地原创文章,转载或复制请以超链接形式并注明出处。
- python字符串join用法是什么?join与加号的取舍 2026-11-20
- jquery常见交互动效失效?从引入到事件绑定的排查顺序 2026-11-22
- 电脑百度网盘下载慢怎么解决?油猴1.4G大压缩包文件3分钟搞定! 2022-05-08
- PHP array_keys() 函数详解:获取数组键名的 N 种姿势 2026-07-02
- hermes接入agnes-ai API实现免费文本生成、文生图、图生图、图生视频 2026-07-20
- python安装错了怎么改?先确认pip指向的解释器路径 2026-11-19
