pip下载慢或超时？切换清华源加速Python库安装

pip 默认从 PyPI 官方服务器（pypi.org）下载包，服务器在海外，国内访问速度不稳定，安装较大的库时经常遇到下载缓慢甚至超时报错。解决办法很直接：把 pip 的下载源换成国内镜像，清华大学开源软件镜像站（TUNA）是其中同步最及时、使用最广泛的选择。下面从临时使用到永久配置，把整个过程讲清楚。

超时报错长什么样

在终端执行 pip install 时，如果网络连接 PyPI 不畅，通常会看到类似这样的错误信息：

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None))
  after connection broken by 'ReadTimeoutError("HTTPSConnectionPool(host='files.pythonhosted.org', port=443):
  Read timed out.")': /packages/...
ERROR: Could not install packages due to an OSError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443):
  Max retries exceeded with url: /packages/...

关键词是 ReadTimeoutError 和 Max retries exceeded。这不是包名写错，也不是 pip 版本有问题，就是网络连接目标服务器太慢。有时不会直接报错，而是进度条长时间停在一个很低的速度（几 KB/s），最终等到默认 15 秒超时后失败。

临时指定清华源安装

最快的办法是在安装命令后面加 -i 参数，直接告诉 pip 从清华源下载：

pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

这条命令只对本次安装生效，不会改动任何配置文件。如果你偶尔才遇到下载慢的情况，或者只是想在某台临时服务器上快速装个包，用 -i 就够了。

安装多个包也一样，-i 放在命令末尾即可：

pip install flask requests pandas -i https://pypi.tuna.tsinghua.edu.cn/simple

需要注意的是，-i 后面的地址末尾是 /simple，不是镜像站首页地址。这是 PEP 503 规定的包索引格式，pip 只认这个路径。

永久配置清华源

每次都加 -i 参数比较麻烦。pip 从 10.0 版本开始提供了 config 子命令，可以一行完成全局配置：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

执行后 pip 会自动创建或修改配置文件，之后所有 pip install 命令都会默认走清华源，不需要再加任何参数。

这条命令实际上做了什么？它往 pip 的配置文件里写入了两行内容。配置文件的位置因操作系统而不同：

• Linux / macOS：~/.config/pip/pip.conf（部分旧系统是 ~/.pip/pip.conf）
• Windows：%APPDATA%\pip\pip.ini（通常展开为 C:\Users\用户名\AppData\Roaming\pip\pip.ini）

打开这个文件，内容大致是：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

如果你的 pip 版本较旧（低于 10.0），没有 config 命令，也可以手动创建上面的文件并写入这两行，效果完全一样。

验证配置是否生效

配置完成后，可以用以下命令确认当前 pip 使用的源地址：

pip config get global.index-url

预期输出：

https://pypi.tuna.tsinghua.edu.cn/simple

也可以直接安装一个小包来验证速度变化，比如：

pip install --upgrade pip

观察终端输出中的下载源地址，如果显示的是 tuna.tsinghua.edu.cn 开头的 URL，说明配置已经生效。下载速度也会有明显提升——同样的包从原来可能十几秒才下完，换源后通常一两秒就结束。

在虚拟环境中使用

如果你用 venv 或 virtualenv 创建了虚拟环境，上面的全局配置同样会生效——虚拟环境中的 pip 也会读取用户级配置文件。

但也有一种情况值得注意：如果你在虚拟环境目录下也有一份 pip.conf（位于 venv/pip.conf），它的优先级比用户全局配置更高。这意味着虚拟环境内的配置会覆盖全局设置。这在多数情况下不会造成问题，只是在排查「明明配了清华源还是走官方源」时值得检查。

pip 读取配置的优先级从高到低是：

1. 命令行参数（-i）
2. 环境变量（PIP_INDEX_URL）
3. 虚拟环境配置文件
4. 用户级配置文件（pip config set 写入的）
5. 系统级配置文件

在 requirements.txt 项目中使用

团队协作时经常用 requirements.txt 管理依赖。如果全局已经配置了清华源，直接 pip install -r requirements.txt 就会走清华源，不需要改动文件内容。

如果想在 requirements.txt 里显式指定源（比如确保 CI/CD 环境也能用），可以在文件开头加一行：

-i https://pypi.tuna.tsinghua.edu.cn/simple
numpy==1.24.0
pandas>=2.0
requests

不过这种做法要谨慎：它会覆盖用户本地的全局配置。如果团队成员在海外，反而会因为连清华源慢而受影响。更好的做法是让每个人各自配置本地源，requirements.txt 只负责列出依赖。

常见问题排查

配了清华源还是报超时？

先确认配置确实生效了：运行 pip config list 查看当前所有配置项。如果输出里没有 index-url 指向清华源，说明配置没有写对位置。另一个可能是 DNS 解析有问题——可以先在终端里 ping pypi.tuna.tsinghua.edu.cn 看看能不能通。

安装时提示"不是受信任的主机"？

这通常出现在公司内网环境中，HTTPS 流量被代理或防火墙拦截。这时可以临时添加 --trusted-host：

pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

如果经常遇到，可以在配置文件中加入：

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

某个包在清华源上找不到？

清华源每五分钟同步一次 PyPI，绝大多数包都能找到。但如果一个包刚刚发布新版本（几分钟内），镜像可能还没同步。这种情况下可以临时用 -i https://pypi.org/simple 切回官方源安装那一个包，其他包继续走清华源。

想恢复为官方源？

如果以后不再需要清华源（比如搬到了海外服务器），执行：

pip config unset global.index-url

pip 会删除配置文件中的 index-url 条目，恢复默认行为。

其他国内镜像源

除了清华源，国内还有几个常用的 PyPI 镜像，遇到清华源偶尔维护或访问异常时可以作为备选：

• 阿里云：https://mirrors.aliyun.com/pypi/simple
• 中国科技大学：https://pypi.mirrors.ustc.edu.cn/simple
• 豆瓣：https://pypi.douban.com/simple

配置方法和清华源完全相同，只需把 URL 替换掉。清华源和中科大源同步频率较高（五分钟级别），包的覆盖和更新及时性上表现最好，一般优先考虑这两个。

整个过程就是这样。一行 pip config set 命令，就能省去以后每次安装包时等待超时的烦恼。如果在服务器上批量部署 Python 环境，建议把这行命令加进初始化脚本里，和安装 Python 本身放在一起执行。