pip 换清华镜像源：临时、永久、用户级三种方式的区别和坑

国内用 pip 装 Python 包，默认从 pypi.org 拉取，速度常常只有几十 KB/s,甚至直接超时。根因是请求要绕到海外的 CDN,换个国内镜像源就能解决。

下面讲清楚镜像源到底改了什么，以及临时、永久、用户级三种配置方式的区别和各自的坑。

默认源为什么慢

pip 安装一个包时做两件事：先从 index-url 拉取该包的版本列表(有哪些版本、每个版本的下载链接),再从列表里的链接下载真正的 wheel 或 sdist 文件。

默认 index-url 是 https://pypi.org/simple。PyPI 本身只是个索引，实际包文件托管在 files.pythonhosted.org,CDN 节点主要在海外。所以哪怕你带宽够，单连接到海外节点的延迟和丢包就足以把速度压下来。

换成镜像源后，镜像站既提供版本列表，也直接提供文件下载，两步都走国内服务器，这是速度差别的来源。

临时换源：只对单次命令生效

1
pip3 install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

-i 参数只对这一条命令生效，不写任何配置文件。

适合不想动全局配置的场景，比如临时跑个脚本，或者在 CI 里显式指定源以避免依赖机器环境。缺点是每次都要带一长串参数。

永久换源：写进配置文件

pip 启动时会从几个固定位置读配置，改一次以后所有命令都生效。用户级配置文件位置：

  • Linux / macOS:~/.config/pip/pip.conf(老路径 ~/.pip/pip.conf 仍然会被读取)
  • Windows:%APPDATA%\pip\pip.ini

文件内容：

1
2
3
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

[global] section 下的配置对所有 pip 命令生效。

关于 trusted-host:当镜像站走 HTTP、或证书校验失败、或 pip 版本较老时,pip 会报 SSL 告警并拒绝下载，加 trusted-host 就是告诉 pip 信任这个主机、跳过校验。清华源走 HTTPS 且证书正常，现代 pip 其实不需要这一行，但加上无害，所以多数教程都留着。知道它的作用后，你就能判断什么时候真的需要加。

用命令代替手写：pip config set

手写配置文件容易拼错路径或字段,pip 自带配置管理命令直接帮你写：

1
2
pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip3 config set global.trusted-host pypi.tuna.tsinghua.edu.cn

这里有个容易混淆的点：命令里的 global 是配置文件的 section 名(对应 [global]),意思是“对所有 pip 命令生效的配置”,并不是“全系统级别”。这条命令默认写入用户级配置文件，等价于上一节手写的那份。

如果想写到别的级别，可以用 --site / --global / --user 指定，比如 --site 会写到当前虚拟环境里，只影响该环境。

验证

1
pip3 config list

输出里看到 global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple' 就生效了。再随便装个小包看下载速度即可确认。

常见坑

配置了还是慢。 pip 读配置有优先级：命令行参数 > 环境变量 > site 级 > user 级 > global 级。如果你在虚拟环境里有 site 级配置，它会覆盖你刚写的 user 级。用 pip3 config list -v 可以看到每一项分别来自哪个文件、哪个级别，排查覆盖问题很方便。

报 SSL / 证书错误。 确认 trusted-host 写的是镜像站域名，且 index-url 用的是 HTTPS。某些公司内网会劫持 HTTPS,这种情况要么换网络，要么不得已再用 HTTP + trusted-host。

恢复默认源。 删掉配置项即可：

1
2
pip3 config unset global.index-url
pip3 config unset global.trusted-host

或者直接删掉 pip.conf / pip.ini 里对应行。

刚发布的新包装不上。 镜像源不是实时同步，清华源大约每 5 分钟同步一次，偶尔有几十分钟延迟。如果你装的是刚发布几小时的包，可能镜像还没有，这种情况临时用 -i https://pypi.org/simple 回官方源装一次。

不只清华：其他可用镜像

清华源不是唯一选择，国内常用镜像还有：

镜像 index-url
阿里云 https://mirrors.aliyun.com/pypi/simple/
中科大 https://pypi.mirrors.ustc.edu.cn/simple
腾讯云 https://mirrors.cloud.tencent.com/pypi/simple
清华 https://pypi.tuna.tsinghua.edu.cn/simple

速度差别不大，按你所在网络选一个稳定即可。我个人用清华，没遇到过同步问题。

清华镜像站还提供 conda、npm、Docker 以及各 Linux 发行版的镜像，完整列表见 https://mirrors.tuna.tsinghua.edu.cn/ 。如果你还在用 conda,顺手把 conda 源也换了，逻辑一样：改的是索引地址，省的是跨境往返。