Python pip安装扩展包太慢？配置国内镜像源加速下载

在使用 Python 的包管理工具 pip 安装第三方扩展库时，下载速度经常只有几十 KB/s，甚至频繁出现 ReadTimeoutError 或连接重置而中断安装。这通常是因为默认下载源指向境外的 PyPI 官方服务器。解决该问题的核心方法就是将下载源切换到国内的高校或云厂商镜像站，无论是单次命令临时加速还是系统级永久配置，只需几步即可让下载速率提升数十倍。

一、为什么 pip 默认下载速度极慢？

Python 官方软件仓库（PyPI，全称为 Python Package Index）的主机设立在海外。当我们执行 pip install numpy 等命令时，客户端会直接向官方服务器 pypi.org 与其 CDN 域名发起元数据查询和安装包二进制文件（.whl 或 .tar.gz）下载请求。

由于跨国网络传输存在物理距离长、国际网关拥堵以及路由波动等问题，国内用户直接访问时网络延迟通常在 200ms 到 400ms 以上，遇到体积较大的机器学习或科学计算包（例如 PyTorch、TensorFlow 或 OpenCV）时，很容易由于耗时过长触发 pip 默认的超时限制而直接报错。

图 1：pip 默认海外访问与国内镜像源加速链路对比

国内的高校开源镜像站与大型云计算服务商通过定时向 PyPI 官方同步完整的软件包副本，并在国内部署了高速 CDN 节点。将 pip 的索引地址指向这些镜像站后，下载请求直接在境内机房响应，能够充分跑满本地带宽。

二、常用的国内高质量 PyPI 镜像源地址

目前国内有若干个长期维护、稳定性高且同步频率以分钟级计算的镜像源。在配置时，需要使用带有 /simple 路径的完整 URL：

三、方案一：临时单次使用镜像源

如果只是偶尔下载某一个包，或者临时在一个未受信任的环境中安装，不需要修改系统的全局配置文件，可以通过命令行参数 -i（或 --index-url）在单次执行时指定镜像站。

1. 标准单次命令语法

pip install <扩展包名称> -i <镜像源URL>

2. 具体使用示例

例如，使用清华大学镜像源安装 requests 库：

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

安装特定版本，或者批量安装 requirements.txt 时同样支持：

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

3. 遇到非 HTTPS 时的信任参数

若使用的镜像源没有配置受信任的 SSL 证书或局域网自建 HTTP 源，pip 会默认拒绝下载。此时需要补充 --trusted-host 参数（只包含域名，不带协议与路径）：

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

四、方案二：永久配置国内镜像源（推荐）

单次输入参数每次都要复制长网址，并不方便。推荐直接将国内镜像源写入 pip 的全局配置文件。一旦配置完成，后续所有常规的 pip install 命令都会自动走高速通道。

图 2：永久配置国内镜像源的操作与生效流程

方法 1：命令行一键设置（官方原生命令，推荐）

自 pip 10.0.0 版本起，官方内置了 pip config 管理命令。用户无需手动寻找路径或新建文件，在终端或命令提示符中执行以下命令即可：

# 将默认下载源配置为清华大学镜像
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# （可选）配置域名信任，避免部分内网环境出现安全校验告警
pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn

如果想使用阿里云镜像源，只需替换对应 URL 和 host：

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

命令执行后，终端会打印出写入的目标文件绝对路径，例如 Writing to C:\Users\Username\AppData\Roaming\pip\pip.ini 或 Writing to /home/user/.config/pip/pip.conf。

方法 2：手动创建与修改配置文件

如果当前机器没有网络交互，或者需要将配置固化到系统镜像、Docker 容器中，可以直接在各系统的默认目录下新建配置文件。

图 3：Windows、Linux 与 macOS 各自的配置文件存放路径与文本格式

各系统的对应配置文件具体位置与操作方法如下：

• Windows： 在文件资源管理器地址栏输入 %APPDATA% 回车（通常进入 C:\Users\<用户名>\AppData\Roaming）。在此目录下新建名为 pip 的文件夹，在里面创建 pip.ini 文本文件（注意确保后缀是 .ini 而非 .ini.txt）。
• Linux： 终端执行：

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

• macOS： 终端执行：

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

五、验证配置是否成功生效

完成上述配置后，可以通过以下两步进行校验：

1. 查看当前已生效的配置列表

pip config list

如果输出如下类似内容，说明配置已经成功写入：

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

2. 进行一次实际扩展包安装

尝试安装一个常用扩展包（例如 wheel 或 six），观察终端中打印的下载 URL：

pip install wheel

终端控制台在 Downloading ... 一行中应当显示来自 pypi.tuna.tsinghua.edu.cn 或 mirrors.aliyun.com 的下载链接，并且下载速度能够迅速跑满带宽。

六、常见问题与进阶排查指南

图 4：pip 镜像源异常排查与进阶设置

1. 如何配置主备多个源（额外源 fallback）？

如果日常主要使用国内镜像，但有时需要安装刚刚发布几分钟的最新库、或者某些未被镜像的私有内部库，可以使用 extra-index-url 配置备选源。pip 在检索包时，会先查询主源 index-url，若未找到则会自动到备用源中搜索：

# 设置清华为主要镜像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 将官方 PyPI 设置为备用源
pip config set global.extra-index-url https://pypi.org/simple

2. 怎么恢复默认的官方源？

如果镜像站临时维护，或者因特定需求需要还原到官方默认源，只需使用 unset 命令移除该配置项：

# 移除配置的镜像源地址
pip config unset global.index-url

# 如果设置过 trusted-host，也可以一并移除
pip config unset install.trusted-host

移除后，pip 会自动回退到官方内置的默认源。

3. 清理残留的损坏缓存

在未配置镜像源前，因断流导致的不完整下载包有时会被保存在 pip 的本地缓存区中，导致即便换了源也报错 Hash mismatch。这时执行一次清理即可彻底解决：

pip cache purge

七、总结

解决 Python pip 下载缓慢的问题，最推荐的做法是通过 pip config set global.index-url <镜像源URL> 进行全局永久绑定。清华源、阿里源和中科大源都是经过长期验证的高可用选择。遇到网络警告时配合 trusted-host，需要双重保障时配合 extra-index-url，即可确保在任何开发环境下都能享受稳定、高速的依赖包构建体验。