怎么解决Python库安装速度慢？配置国内镜像源加速pip下载

在使用 Python 开发时，使用 pip install 安装第三方库出现下载速度仅有几十 KB/s、频繁出现连接超时（ReadTimeoutError）甚至中断失败，根本原因在于 pip 默认从国外的官方 PyPI 服务器下载包资源。解决这个问题的核心方法是将下载地址切换至国内高校或云厂商提供的 PyPI 镜像源。本文将介绍国内主流镜像站地址、单次临时加速指令、全局永久配置命令，以及在不同操作系统中直接修改配置文件的方法。

一、为什么 pip 默认安装速度慢？

Python 官方维护的第三方包索引服务名为 PyPI（Python Package Index），其核心服务器节点主要部署在海外。当我们执行 pip install 包名 时，终端会自动向官方源发起网络请求以获取对应软件包元数据和 .whl 安装文件。

由于跨国网络传输存在物理距离长、国际网关路由跳数多以及带宽限制等因素，直接从海外官方节点下载不仅连接建立耗时长，而且在遇到体积较大的包（如 numpy、pandas、torch 等）时极易发生网络超时。国内的大学和企业通过定期与官方 PyPI 服务器进行完整镜像同步，在大陆境内搭建了高速缓存节点。将 pip 指向这些本地镜像站，下载请求即可走国内高带宽骨干网，从而实现数兆甚至几十兆每秒的平稳下载。

图1：官方 PyPI 与国内镜像站的网络传输架构与下载机制对比

二、常用优质国内镜像源汇总

国内有多家高校与云服务商提供了稳定且定期同步的开源镜像服务。选择时推荐优先使用清华大学或阿里云源，两者的同步频率与服务可用性均长期保持在高水平：

三、方法一：临时使用镜像源（单次生效）

如果只是偶尔需要安装某个库，或者临时在一台临时运行环境、容器中执行安装任务，可以使用 -i（或 --index-url）参数指定镜像源。该参数仅对当前单次执行生效，不会改动系统的全局设置。

1. 标准命令语法

pip install <package_name> -i <mirror_url>

2. 具体执行示例

以安装常用数据处理库 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.1 MB/s eta 0:00:00
Installing collected packages: requests
Successfully installed requests-2.31.0

3. 遇到不受信任主机提示的处理方法

在少数内网或定制镜像环境中，若终端抛出 The repository located at ... is not a trusted or secure host 报错，可以附加 --trusted-host 信任参数：

pip install requests -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

四、方法二：使用 pip 命令一键永久配置（推荐）

在日常开发中，每次输入长网址显然繁琐低效。pip 自 10.0.0 版本起内置了 config 指令，允许用户直接在终端中一键修改全局下载源，无需手动寻找和创建复杂的系统配置文件。

图2：使用 pip config 永久配置加速源的标准化步骤

1. 设置全局镜像源

打开终端（Windows 的 PowerShell 或 CMD、macOS/Linux 的 Terminal），输入以下命令并回车：

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

终端会提示类似如下信息，表示已自动创建并写入配置文件：

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

2. （可选）配置 trusted-host

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

3. 查看当前生效的配置

如果想确认当前有哪些配置项已生效，可执行：

pip config list

示例输出：

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

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

若你的环境使用的是较老版本的 pip，或需要在 Docker 镜像构建、自动化脚本及团队统一规范中批量管理配置，直接在各操作系统的指定路径下创建配置文件是最稳妥的方式。

图3：多平台 pip 配置文件存储路径与文件格式对照

1. 配置文件通用内容

无论是哪个操作系统，配置文件内部的内容格式完全一致（标准的 INI 语法结构）：

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

2. Windows 系统具体操作步骤

1. 按快捷键 Win + R 打开“运行”窗口，输入 %APPDATA% 并按回车，进入当前用户的 AppData\Roaming 文件夹。
2. 检查是否存在名为 pip 的文件夹；若不存在，新建该文件夹。
3. 进入 pip 文件夹，新建文本文件，重命名为 pip.ini（注意确保显示文件扩展名，防止保存为 pip.ini.txt）。
4. 使用记事本打开该文件，粘贴上述 INI 内容并保存。

3. macOS 与 Linux 系统具体操作步骤

在终端中直接通过一行命令完成文件夹创建并写入配置内容：

mkdir -p ~/.pip && cat <<EOF > ~/.pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

六、两种配置方式的对比与选择建议

对于初学者或开发者个人电脑，推荐优先使用 pip config set 命令，简单且不会出现创建隐藏文件和路径拼错的问题；若需要为团队统一配置开发环境或编写自动化脚本，直接维护统一的 pip.conf / pip.ini 文件更为规范高效。

七、常见排查与避坑事项

• 问题一：配置后下载仍然显示官方源
  排查当前虚拟环境是否有自己的局部配置文件，或者终端中是否有开启了特定网络代理（如 HTTP_PROXY / HTTPS_PROXY 环境变量）。可执行 pip config list --show-origin 查看各个配置项的具体生效来源文件。
• 问题二：提示“找不到匹配版本” (No matching distribution found)
  镜像源一般有数分钟到数小时的同步延时。若某个第三方库刚刚在官方发布了最新版本（例如发布仅数分钟），国内镜像源可能尚未同步完毕。此时可暂时使用官方源或单次指定临时源安装该特定版本。
• 问题三：恢复默认官方源的方法
  如果需要切回官方原生源，直接在终端执行：

  pip config unset global.index-url

  即可移除自定义的全局镜像配置，恢复默认下载逻辑。

八、全文小结

遇到 Python 安装库缓慢的问题无需焦虑，核心步骤非常直接：

图4：Python 开发者加速 pip 的全流程回顾与行动要点

通过配置国内镜像源，能够显著缩短依赖库下载时间，避免因网络波动或中断打断开发节奏。日常使用时配置清华源或阿里源即可满足绝大部分场景的需求。