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

在日常使用 Python 安装第三方库时，执行 pip install 经常会遇到下载进度只有几 KB/s 甚至直接抛出 ReadTimeoutError 超时报错的情况。这个问题的根本原因在于 pip 默认从位于境外的官方 PyPI（Python Package Index）服务器拉取数据，受跨洋网络链路抖动、带宽限制以及节点距离影响，下载体验极不稳定。解决该问题最直接且有效的方法，就是将安装源替换为国内高校或大型云厂商搭建的 PyPI 镜像源。

一、单次临时换源安装：快速解决燃眉之急

如果你只是偶尔在没有配置环境的机器上下载某个库，或者不想修改系统全局配置，可以在执行 pip install 时通过 -i（或 --index-url）参数临时指定镜像站地址。

1. 基本命令语法

pip install <第三方库名称> -i <镜像源地址>

例如，使用清华大学镜像源安装常用的网络请求库 requests，只需在终端中运行以下命令：

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

终端在解析到该参数后，会直接从指定的清华镜像源检索包的元数据与 wheel 安装包，下载速度通常能够达到几兆甚至几十兆每秒。

2. 常用优质国内镜像源地址列表

二、永久配置国内镜像源：一劳永逸的加速方案

每次手动输入 -i 参数繁琐且容易遗忘。通过配置本地配置文件，可以让 pip 无论在终端安装还是 IDE（如 PyCharm、VS Code）内自动解析依赖时，都默认通过国内镜像源下载。

方法 1：命令行一行命令自动配置（官方推荐，跨平台通用）

自 pip 10.0.0 版本起，官方内置了 pip config 指令。无需手动创建或寻找复杂的系统路径，只需在终端（Windows 的 PowerShell/CMD、macOS 的 Terminal 或 Linux 终端）中依次运行以下命令即可：

# 1. 设置默认镜像源为清华大学开源镜像站
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 2. （可选但建议）将该主机域名标记为可信域名，避免特定网络环境下 SSL 握手阻断
pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn

执行完成后，pip 会直接在屏幕输出配置写入的具体文件路径。例如在 Windows 下会显示：

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

在 Linux 或 macOS 下通常会显示：

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

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

如果当前环境版本较旧不支持 pip config，或者在编写 Dockerfile / 自动化脚本时需要直接固化文件，可以直接在对应的操作系统路径下手动创建文件。

打开或新建对应配置文件后，写入以下标准 INI 格式内容并保存：

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

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

各项参数说明：

• index-url：第三方库的基础索引地址。pip 在执行查找和下载时都会直接访问该 URL。
• timeout：网络超时时间，默认通常为 15 秒，适当延长至 60 秒可防止个别大体积包在握手时发生超时中断。
• trusted-host：授权信任该域名，解决部分环境因 SSL 自签名或证书链检验不全引发的警告。

三、验证与测试配置结果

完成配置后，必须通过命令验证配置是否真正生效，以及安装时是否已走国内节点。

1. 查看当前已加载的配置项

pip config list

正常情况下，终端会输出当前生效的键值对，例如：

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

2. 进行一次实际安装测试

直接执行常规的安装命令（无需添加 -i 参数）：

pip install numpy

如果希望更明确地确认数据流来源，可以加上 -v（详细输出）参数：

pip install numpy -v

在滚动的日志中，查找以 Looking in indexes: ... 开头的行。如果后面显示的网址为你配置的镜像站地址（如 https://pypi.tuna.tsinghua.edu.cn/simple），说明镜像源配置已完全生效，下载速度通常会提升十倍以上。

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

1. 某些刚发布的新版本库在镜像源中找不到

国内镜像站是通过定时任务与官方 PyPI 服务器进行增量同步的，不同镜像站的同步间隔从几分钟到数小时不等。如果某个包作者刚刚发布了全新版本，或者该包属于极冷门的新建项目，镜像源可能尚未同步完成，此时 pip 会报错 No matching distribution found。

解决办法：临时切回官方源安装该包，或者在配置中设置额外备用源：

pip install <package_name> -i https://pypi.org/simple

或者在配置文件中追加 extra-index-url：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
extra-index-url = https://mirrors.aliyun.com/pypi/simple/ https://pypi.org/simple

这样当首选镜像源找不到包时，pip 会自动回落到备用源中继续查找。

2. 报错 SSL: CERTIFICATE_VERIFY_FAILED

如果在公司内网、学校校园网或开启了特定代理软件，可能因为本地证书信任链不完整导致 SSL 校验失败。此时确保已在配置文件中加入 trusted-host = 镜像站域名（注意仅填写域名，不带 https:// 前缀和尾部路径）。

3. 虚拟环境（venv 或 conda）中的配置继承关系

如果你在项目中使用 python -m venv .venv 创建了虚拟环境，该虚拟环境默认会自动继承当前系统用户级的 pip.conf 或 pip.ini 配置。如果你希望某个项目单独绑定特定镜像源，可以直接在虚拟环境根目录下创建对应的 pip.conf 文件，其优先级将高于全局配置。

总结

配置国内镜像源是每一位 Python 开发者配置新工作环境时的必备基础操作。对于日常开发，强烈推荐直接使用 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple 进行全局绑定；在临时调试或服务器快速构建时，可灵活搭配 -i 参数。合理配置镜像源后，既能规避频发的网络中断超时，也能大幅提升项目依赖部署的整体效率。