怎么永久修改 pip 默认镜像源加速 Python 库安装

在使用 Python 进行项目开发时，通过 pip install 安装第三方扩展包是几乎每天都要进行的操作。许多人在执行安装命令时经常遇到下载极慢、进度条长时间停滞，甚至直接报出 ReadTimeoutError 或连接重试失败的错误。这是因为 pip 默认连接的是部署在海外的 PyPI（Python Package Index）官方服务器，国际网络链路的延迟与波动直接制约了下载体验。

将索引源永久替换为国内高校或大型云厂商维护的同步镜像源，是解决这一问题的最有效途径。国内镜像源通过高带宽节点与官方源保持准实时同步，不仅速度快，而且无需每次安装都手动附加 -i 参数。

一、常用的优质国内镜像源列表

国内有多家知名高校与大型云服务商对外提供稳定的 PyPI 镜像服务。根据 PEP 503 规范，所有符合标准的镜像站均提供名为 /simple 的简易索引接口。在配置时，务必保留完整的 /simple 路径：

二、方法一：使用 pip config 命令行设置（推荐）

自 pip 10.0.0 版本起，官方内置了配置管理命令 pip config。这种方法的最大优势在于：无需读者关心当前操作系统究竟将配置文件保存在哪一级目录、无需手动创建文件夹，命令执行后会自动定位或生成对应的配置文件。

步骤 1：打开终端环境

Windows 用户按下 Win + R 键输入 cmd 或 powershell 并回车；macOS 与 Linux 用户直接打开系统自带的终端（Terminal）程序。不需要以管理员或 root 身份打开，普通用户权限即可配置当前用户的默认环境。

步骤 2：执行写入配置命令

以清华大学镜像源为例，在终端中输入并执行以下命令：

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

如果希望使用阿里云镜像源，则执行：

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

执行完成后，终端会返回类似如下的信息，明确指出写入的文件位置与具体键值：

Writing to C:\Users\Username\AppData\Roaming\pip\pip.ini

步骤 3：查看当前已生效的配置列表

执行以下命令即可打印出当前 pip 识别到的全部配置：

pip config list

若终端输出显示 global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'，则说明默认镜像源已经永久写入成功。

三、方法二：手动创建或修改配置文件

在某些特殊的无终端交互环境、Docker 基础镜像构建或批处理部署脚本中，可能需要通过直接创建文件的方式来配置 pip。不同操作系统下配置文件的存储路径和扩展名略有不同。

1. Windows 环境下的配置文件

在 Windows 系统中，pip 的用户级配置文件名为 pip.ini，位于用户应用数据目录中：

• 标准路径：%APPDATA%\pip\pip.ini
• 展开后的实际位置：C:\Users\<您的用户名>\AppData\Roaming\pip\pip.ini

如果该路径下不存在 pip 文件夹，可在资源管理器地址栏输入 %APPDATA% 进入目录，新建名为 pip 的文件夹，随后在其中新建文本文件并重命名为 pip.ini。使用记事本打开该文件，写入如下内容并保存：

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

2. macOS 与 Linux 环境下的配置文件

在基于 Unix 的系统中，配置文件名为 pip.conf。根据现代系统的 XDG 目录标准，首选路径为当前用户家目录下的 .config 文件夹：

• 首选标准路径：~/.config/pip/pip.conf
• 传统兼容路径：~/.pip/pip.conf

在终端中可以通过两行命令快速创建目录并写入内容：

mkdir -p ~/.config/pip
cat <<EOF > ~/.config/pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 120
EOF

四、验证配置生效与安装测试

配置完成后，可以通过以下两个步骤确认 pip 是否已经真正使用国内镜像源进行下载：

1. 查看配置来源与明细

使用带有详细参数的 -v 选项查看配置项的来源文件：

pip config list -v

终端会输出类似下面的内容，明确打印出具体从哪个配置文件中读取到了 global.index-url：

For fetching:
  global.index-url: https://pypi.tuna.tsinghua.edu.cn/simple (from C:\Users\Username\AppData\Roaming\pip\pip.ini)

2. 进行实际安装测试

以安装体积较小的轻量级库（例如 requests）为例，附加详细输出参数 -v：

pip install requests -v

观察控制台的日志输出，定位 Looking up "https://..." in the cache 或 Downloading ... 这一行。如果 URL 的前缀已经变成 pypi.tuna.tsinghua.edu.cn 或 mirrors.aliyun.com，说明请求已成功定向到国内镜像站，下载将在极短时间内完成。

五、常见问题排查与注意事项

1. 遇到 SSL 证书验证失败或“not trusted”警告

如果由于特定内网代理或操作系统根证书缺失，导致 pip 提示 The repository located at ... is not a trusted or secure host，可以通过命令将镜像站的域名加入信任列表：

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

执行后，配置文件的 [install] 小节会自动添加该域名，后续安装将不再阻断。

2. 虚拟环境（Virtualenv / venv / Conda）是否生效？

在绝大多数情况下，通过用户目录配置的全局镜像源会对当前用户创建的所有 venv 与 conda 虚拟环境生效。pip 的配置读取顺序为：

1. 环境级配置：虚拟环境根目录下的 pip.conf 或 pip.ini（优先级最高）；
2. 用户级配置：上述 pip config 默认修改的当前用户主目录配置（日常使用推荐）；
3. 系统级配置：位于系统通用目录（如 Linux 下的 /etc/pip.conf）。

若在某个特殊虚拟环境中发现源未生效，可以直接在该虚拟环境的主目录下放置上述 pip.ini 或 pip.conf 文件，实现针对单个隔离环境的独立定制。

3. 需要临时安装刚刚发布的新版本包

国内镜像源与官方 PyPI 通常保持几分钟至数十分钟的同步周期。如果某个库刚发布了几分钟、国内镜像站尚未同步完成，读者无需撤销已配置好的永久镜像源，只需在单次执行命令时加上 -i 参数指定官方源即可：

pip install package-name -i https://pypi.org/simple

命令行参数的优先级高于配置文件，安装完毕后，后续操作仍会自动继续沿用国内镜像加速。