Python库下载慢？配置pip国内镜像源加速安装

图 0：pip 国内镜像源加速方案总览

一、为什么 pip 下载会慢？官方源与国内镜像原理

pip 是 Python 官方推荐的第三方包管理工具。在默认状态下，每当你执行 pip install <package> 时，pip 都会向官方索引仓库 PyPI (Python Package Index) 发起检索与下载请求。

PyPI 的主服务器部署在海外，由于跨国网络链路长、国际出口带宽受限以及网络波动等因素，国内主机在访问 PyPI 时往往存在明显的网络延迟。特别是当安装体积较大的科学计算或机器学习库（如 NumPy、Pandas、PyTorch 等）时，常常伴随下载速率过低（十几 KB/s）甚至报出 ReadTimeoutError 或 ConnectionResetError 异常。

国内高校与主流云服务提供商（如清华大学、中科大、阿里云、腾讯云等）部署了 PyPI 镜像服务器。这些镜像站点定期、自动化地将官方 PyPI 的包元数据与安装文件完整同步到国内的高速服务器与 CDN 节点上。切换镜像源后，你的下载请求将直接由国内优质节点响应，下载速率可轻松提升数倍至数十倍。

图 1：PyPI 官方源直连与国内镜像源同步链路对比

二、主流国内 pip 镜像源地址汇总与选择

国内有多家声誉良好、长期稳定运行的开源镜像站。在配置前，你可以根据所在网络环境（校园网、教育网、公网或云服务器）进行选择：

三、两种加速方案与具体配置步骤

根据使用需求，配置镜像源通常有两种方式：临时单次指定与永久全局配置。如果只是临时测试一个包，可以使用临时参数；日常开发中更推荐直接进行永久配置，一劳永逸。

图 2：pip 镜像源配置决策与实施路径图

方法一：临时单次使用镜像源（无需改动任何配置）

如果你只是在某台临时机器上快速下载单个库，或者想测试特定镜像源的当前网络连通性，可以在安装命令后附加 -i（即 --index-url）参数。

命令示例：临时使用清华大学镜像源安装 requests 库：

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

终端运行输出示例：

Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple
Collecting requests
  Downloading https://pypi.tuna.tsinghua.edu.cn/packages/.../requests-2.31.0-py3-none-any.whl (62 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 62.6/62.6 kB 2.8 MB/s eta 0:00:00
Installing collected packages: requests
Successfully installed requests-2.31.0

可以看到，第一行即明确显示正在清华源索引检索，下载速率达数兆每秒。这种方式仅对当前这一次命令有效，下一次执行普通 pip install 依然会访问默认源。

方法二：永久全局配置（推荐：使用 pip 官方命令）

从 pip 10.0 版本开始，官方内置了 pip config 子命令。这是目前最稳妥、最跨平台的配置方式，它会自动根据你当前的操作系统选择正确的配置文件存放路径，并自动建立父级目录，无需手动寻找复杂的系统隐藏路径。

步骤一：打开系统终端

• Windows 系统：按 Win + R 键，输入 cmd 或 powershell 并回车。
• macOS / Linux 系统：打开“终端”（Terminal）。

步骤二：执行全局镜像源设置命令

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

终端运行输出示例：

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

（若在 Windows 下运行，输出将提示写入到类似 C:\Users\username\AppData\Roaming\pip\pip.ini 路径）。

步骤三：设置额外的信任主机（建议补充）

部分公司局域网或较旧版本环境在访问部分域名时可能提示 SSL 警告，建议将域名加入信任列表：

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

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

在某些无法直接通过交互命令行配置的服务器或容器模板中，你可以直接手动创建配置文件。不同操作系统下的默认路径有所不同：

图 3：各系统 pip 配置文件存储路径与文件内容结构

若对应目录尚不存在，需先手动建立对应目录：

• Windows：在资源管理器中创建 pip 文件夹，并在其内新建文本文档，重命名为 pip.ini（注意显示文件扩展名，防止误存为 pip.ini.txt）。
• macOS / Linux：打开终端执行：

  mkdir -p ~/.config/pip
  nano ~/.config/pip/pip.conf

  将上述 INI 配置内容粘贴后保存即可。

四、如何验证配置是否成功

配置完成后，建议通过以下两步验证，确保镜像源已正确生效且下载畅通。

第一步：检查当前生效的配置项

在任意终端窗口中执行：

pip config list

预期正确输出：

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

若能够正确列出 global.index-url，说明 pip 已正确识别并读取到了配置文件。

第二步：执行轻量库安装测试

选择一个体积适中的常用第三方库进行安装测试，例如 urllib3：

pip install urllib3

观察输出重点：安装过程中终端首行是否打印出类似 Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple，并且随后的 Downloading ... 链接也是由该镜像域名下发。如果地址符合且进度条在极短时间内完成，即证明国内镜像源加速成功。

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

1. 报错“SSL: CERTIFICATE_VERIFY_FAILED”或不可信主机提醒

某些由于内网代理、中间人拦截或较旧版本的 Python 环境，可能会阻断对国内镜像源的 HTTPS 证书校验。

解决办法：在配置文件中补充 trusted-host 字段，或通过命令行添加：

pip config set install.trusted-host mirrors.aliyun.com

注意：trusted-host 只需要填写纯域名，不要包含 https:// 协议头或 /simple 路径。

2. 为什么在虚拟环境（venv / conda）中没有生效？

默认情况下，使用 pip config set global.index-url 写入的是当前操作系统的用户级配置文件（User level），通常新建的标准 Python 虚拟环境（如 venv 或 virtualenv）会自动继承该配置。

但如果该虚拟环境自身有独立的 pip.conf / pip.ini，或者当前 shell 环境中预设了 PIP_INDEX_URL 环境变量，环境变量将享有更高的优先级并覆盖配置文件。若发现未生效，可在激活虚拟环境后运行 pip config debug 命令，查看各层级配置文件的读取与覆盖详情。

3. 如何恢复默认的官方 PyPI 源？

如果日后需要恢复默认的 PyPI 官方源，无需删除整个 pip 软件，只需清除配置文件中的该设置项：

pip config unset global.index-url
pip config unset install.trusted-host

删除后再次执行 pip config list，若无相关输出，pip 就会自动回退到官方默认源。

图 4：国内镜像源地址与常用 pip 配置命令速查图