pip install requirements.txt 太慢？一文教你用国内镜像源提速 8 倍

加速 Python 依赖安装：使用国内镜像源优化 pip install -r requirements.txt

在 Python 开发中，我们经常通过 pip install -r requirements.txt 批量安装项目依赖。然而，默认连接的官方 PyPI 源（https://pypi.org）位于海外，受网络延迟和带宽限制，国内用户常常遭遇下载速度慢、连接超时、甚至安装失败等问题。本文将系统性地介绍如何通过配置国内镜像源，显著提升 pip 安装效率，并提供永久性解决方案，适用于个人开发、CI/CD 流水线及团队协作场景。

1 问题背景与性能瓶颈分析

1.1 为什么 pip 安装速度慢？

pip 默认从 Python Package Index（PyPI）下载包，该服务由 Python 软件基金会维护，服务器主要部署在美国。对于中国大陆用户，存在以下瓶颈：

• 高网络延迟：跨洋链路往返时间（RTT）通常 >200ms；
• 带宽限制：国际出口带宽竞争激烈，尤其在高峰时段；
• DNS 解析慢：部分网络环境对海外域名解析效率低；
• 连接不稳定：易因超时导致安装中断，需反复重试。

实测数据显示，在未使用镜像的情况下，安装一个包含数十个依赖的 requirements.txt 文件可能耗时 5–15 分钟，甚至失败。

1.2 国内镜像源的优势

国内高校和云服务商提供了 PyPI 官方同步镜像，具备以下优势：

• 就近访问：部署在中国大陆，RTT < 30ms；
• 高速带宽：千兆级出口，下载速度可达 10–50 MB/s；
• 自动同步：通常每 5–10 分钟同步一次官方源，保障包的新鲜度；
• 免费开放：无需认证，直接使用。

✅ 所有国内主流镜像均遵守 PyPI 镜像协议，内容与官方完全一致，安全可靠。

2 临时加速：单次使用镜像源

2.1 基本用法

在执行 pip install 时，通过 -i 参数指定镜像源 URL：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

注意：URL 末尾的 /simple/ 是必须的，这是 PyPI 镜像的标准接口路径。

2.2 常用国内镜像源对比

以下为目前稳定可用的主流镜像源（截至 2025 年）：

📌 建议：优先使用 清华大学 或 阿里云 镜像，兼顾速度与稳定性。

2.3 避免 SSL 警告：添加 trusted-host

部分旧版 pip 或网络环境可能因证书验证失败报错，可添加 --trusted-host 参数：

pip install -r requirements.txt \
  -i https://pypi.tuna.tsinghua.edu.cn/simple/ \
  --trusted-host pypi.tuna.tsinghua.edu.cn

🔒 安全说明：该参数仅跳过主机名验证，不降低包本身的安全性（包仍通过哈希校验）。

3 永久配置：全局使用国内镜像

3.1 配置原理

通过修改 pip 的配置文件 pip.conf（Linux/macOS）或 pip.ini（Windows），可让所有 pip 命令默认使用指定镜像，无需每次输入 -i。

3.2 配置文件路径与内容

3.2.1 Linux 与 macOS

配置文件路径：
~/.pip/pip.conf 或 ~/.config/pip/pip.conf

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

3.2.2 Windows

配置文件路径：
C:\Users\<你的用户名>\pip\pip.ini

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

💡 提示：若目录或文件不存在，请手动创建。

3.3 验证配置是否生效

运行以下命令查看当前 pip 配置：

pip config list

输出应包含：

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

此后，直接运行 pip install -r requirements.txt 即自动使用国内源。

4 高级技巧与最佳实践

4.1 在 CI/CD 中使用镜像源

在 GitHub Actions、GitLab CI 或 Jenkins 等流水线中，建议显式指定镜像源，避免依赖环境配置：

# GitHub Actions 示例
- name: Install dependencies
  run: |
    pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

4.2 多源故障转移（可选）

可通过 --extra-index-url 指定备用源，但需谨慎使用（可能引入非官方包）：

pip install -r requirements.txt \
  -i https://pypi.tuna.tsinghua.edu.cn/simple/ \
  --extra-index-url https://pypi.org/simple/

⚠️ 警告：仅在必要时使用，避免安全风险。

4.3 保持镜像源更新

虽然镜像会自动同步，但若遇到“找不到某新包”的情况，可：

1. 临时切换回官方源安装；
2. 等待 10 分钟后重试；
3. 检查镜像状态页面（如 清华 TUNA 状态）。

5 性能对比实测（示例）

在相同网络环境下，安装一个包含 42 个依赖的 requirements.txt 文件：

📊 提速效果：6–8 倍速度提升，且安装稳定性显著增强。

6 总结

通过配置国内 PyPI 镜像源，开发者可以轻松解决 pip install 速度慢的问题。无论是临时加速还是永久配置，操作都极为简单，却能带来显著的效率提升。建议每位 Python 开发者将此纳入开发环境初始化流程，尤其适用于：

• 本地开发环境搭建；
• Docker 镜像构建（在 Dockerfile 中指定 -i）；
• 自动化部署与 CI/CD 流水线。

💡 最后建议：将本文中的配置脚本加入你的 dotfiles 或 DevOps 模板库，实现“一次配置，处处高效”。

关键词：pip 镜像源、requirements.txt 加速、国内 PyPI、清华镜像 pip、Python 依赖安装慢