Python清华源最新PyPI镜像地址及pip永久配置教程

陆遥

发布时间：2026-10-24| 6人浏览过

原创

一、清华源最新 PyPI 镜像地址与临时使用

清华大学开源软件镜像站（TUNA）维护的 PyPI 镜像完整同步了官方软件仓库，其最新的标准简易索引地址为：

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

该地址末尾的 /simple 严格遵循 Python 官方的 PEP 503 规范（Simple Repository API），pip 工具通过该规范检索包的版本列表与 Wheel 二进制分发文件。请勿省略末尾路径，也不要使用网页浏览界面的 URL。

若仅需在单次安装测试时使用清华镜像，可以在安装命令后追加 -i 参数指定源地址：

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

临时参数虽然灵活，但每次执行命令都需要输入长串地址，在依赖较多的项目构建或自动化脚本中极易遗漏。因此，将源地址固化到系统或用户全局配置中是更为推荐的做法。

从 pip 10.0.0 版本开始，官方提供了内置的 config 指令。这种方式无需手动定位复杂的系统文件夹或新建文本文件，能够自动跨平台地将参数写入用户层级的默认配置文件中。

在任意终端（Windows 命令提示符 / PowerShell、macOS Terminal、Linux Bash）中直接运行以下单行命令：

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

命令成功执行后，控制台会输出写入的键值以及对应保存的物理路径，例如：

Writing to /Users/username/.config/pip/pip.conf

虽然清华源支持完整的标准 HTTPS 证书链，但在部分内网隔离、老旧系统根证书缺失或自建安全网关环境下，pip 可能会抛出针对源域名的 SSL 警告。可通过附加信任主机项避免此情况：

pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn

在 Docker 镜像构建、无交互自动化部署或没有完整终端环境的场景下，直接生成或编辑配置文件更加直接。不同操作系统中，pip 默认搜索配置文件的物理路径存在差异。

操作系统	用户级默认配置文件路径	文件格式
Windows	`%APPDATA%\pip\pip.ini` (如 `C:\Users\<用户名>\AppData\Roaming\pip\pip.ini`)	INI
macOS	`~/Library/Application Support/pip/pip.conf` 或 `~/.config/pip/pip.conf`	INI / CONF
Linux	`~/.config/pip/pip.conf` 或 `~/.pip/pip.conf`	INI / CONF

如果对应目录或文件不存在，需手动创建文件夹与文件，并在其中填入以下内容：

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

[install]
trusted-host = pypi.tuna.tsinghua.edu.cn

注意：Windows 系统下新建文本文件时，请确保文件拓展名确实为 .ini，避免系统默认隐藏已知拓展名而保存为 pip.ini.txt。文件编码格式应选用标准的 UTF-8 无 BOM 编码。

完成配置后，必须通过验证手段确认当前运行环境读取到了正确的镜像地址，而不是静默回退到了官方源。

执行以下命令即可打印出目前所有生效的配置条目及其来源文件：

pip config list

正常情况下，终端应准确回显：

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

可以通过强制不使用本地缓存的方式安装一个体积较小的测试包（如 requests），并加上 -v 参数观察其实际网络请求主机：

pip install --no-cache-dir requests -v

观察输出日志中获取包元数据的信息，若显示连接的目标主机为 pypi.tuna.tsinghua.edu.cn，即证明配置已全局生效。

网络代理导致国内源反向走代理超时：若本地开发环境中开启了系统级代理或全局 VPN，访问国内的 pypi.tuna.tsinghua.edu.cn 可能会反向绕行海外节点，导致严重的延迟或握手超时。可在终端环境变量中配置 NO_PROXY 排除清华域名：
```
export NO_PROXY="pypi.tuna.tsinghua.edu.cn,tsinghua.edu.cn,$NO_PROXY"
```
个别极新版本包尚未同步：清华源通常以固定周期（几分钟至半小时不等）与官方 PyPI 差量同步。当依赖库刚刚在官方发布数分钟内，镜像可能尚未拉取该 Wheel 包，导致 404 错误。遇到此类情况，无需撤销全局配置，仅对该包临时指定官方源安装即可：
```
pip install package_name==1.2.3 -i https://pypi.org/simple
```
虚拟环境（venv / conda）不读取用户配置：部分激活隔离极其严格的虚拟环境可能不会自动继承外部的用户目录配置。此时可以直接进入该虚拟环境所在根目录，找到或新建 pip.conf（或 Windows 下的 pip.ini），写入相同的 index-url 设置，实现项目级的换源固定。