pip install 下载慢？常用国内镜像源地址及配置方法

一、为什么默认 pip 下载慢：网络链路解析

Python 官方软件仓库（Python Package Index，简称 PyPI）部署在境外，国内终端通过公网访问官方节点时，数据传输需要经过跨洋海底光缆与多跳国际骨干网网关。高峰期国际出口带宽紧张，网络拥塞与高丢包率常使下载速率降至数十 KB/s，大体积依赖包（如 Torch、TensorFlow、Scipy 等）极易直接超时中断。

国内各大高校（如清华大学、中国科学技术大学）和大型科技企业（如阿里云、腾讯云、华为云）设立了公开的开源镜像站。这些镜像站通过自动化同步机制，定期将 PyPI 官方的所有安装包及其元数据克隆至国内机房与 CDN 边缘节点。配置国内镜像源后，请求将直接接入本土高速骨干网，下载速率通常可达数十 MB/s。

图 1：pip 默认 PyPI 跨境链路与国内镜像加速网络拓扑对比

二、常用国内镜像源地址及选择建议

国内镜像站通常由大学开源镜像协会或云厂商基础设施团队维护，完全兼容 PyPI 的 Simple Repository API 标准。配置时需要注意：URL 末尾通常需带有 /simple 或 /simple/ 路径；所有正规镜像均支持 HTTPS 加密连接。

三、临时使用国内源：单次命令指定

如果只是临时安装某个依赖包、或者在未配置环境的测试机中临时排错，无需修改全局配置文件，只需在 pip install 命令后附带 -i（或 --index-url）参数即可。

1. 标准执行命令

# 临时使用清华大学镜像源安装 requests
pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

# 临时使用阿里云镜像源安装 pandas
pip install pandas -i https://mirrors.aliyun.com/pypi/simple/

2. 包含额外信任主机的命令（针对非 HTTPS 或特殊自建源）

现代 pip 默认强制校验 SSL/TLS 证书。如果遇到企业自建内网镜像或使用了非安全协议（http://），pip 会报错并拒绝下载。此时需要附加 --trusted-host 信任域名参数：

# 当镜像源为 HTTP 协议或私有证书时，指定信任域名
pip install requests -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

注意：本文推荐的正规主流国内镜像均已全面配置标准公网 HTTPS 证书，日常安装无需添加 --trusted-host。

图 2：pip 临时单次换源与永久配置的操作流程决策图

四、永久配置国内源：一劳永逸的方法

为了避免每次执行安装命令都输入长串 URL，最省力的方式是进行全局永久配置。目前官方推荐采用内置的 pip config 命令行进行配置；在老旧环境或自动化脚本中，也可以通过直接读写配置文件来实现。

方法一：通过 pip 命令行自动写入（首选推荐）

自 pip 10.0.0 起，官方引入了 pip config 管理子命令。该命令会自动识别当前操作系统的用户规范目录，并在对应位置创建或更新配置文件，免去读者手动寻找路径和排查语法的繁琐步骤。

1. 设置主镜像源（以清华大学源为例）：

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

2. （可选）配置备用镜像源：

如果希望在主镜像源未同步某些特殊包时自动回退搜索备用源，可以配置 extra-index-url：

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

3. 查看当前生效的配置列表：

pip config list

若配置成功，终端将返回类似如下内容：

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

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

如果当前环境的 pip 版本较旧，或正在通过 Dockerfile、Ansible 等脚本批量部署环境，可以直接创建对应的配置文件。不同操作系统下的存储路径如下：

图 3：Windows / macOS / Linux 平台配置文件路径与继承优先级

配置文件具体内容格式（INI 语法）：

无论是 pip.ini 还是 pip.conf，文件内部均采用标准 INI 块配置格式。使用文本编辑器新建对应文件并粘贴以下内容保存：

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

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

五、配置验证与常见问题排查

完成配置后，建议读者通过以下两步验证镜像源是否真正接管了下载请求，并了解遇到异常时的排查对策。

1. 验证配置是否生效

步骤 A：查看全局设置项

pip config list

输出应显示所设置的 global.index-url。

步骤 B：详细模式安装测试

在安装任意小型测试库时附加 -v（verbose 详细输出）参数，观察输出中的下载链接：

pip install six -v

观察控制台中的 Looking in indexes: ... 和 Downloading ... 字段。如果 URL 前缀指向 https://pypi.tuna.tsinghua.edu.cn/ 等国内镜像域名而非 pypi.org，则证明加速配置已完全生效。

图 4：pip 镜像源常见故障现象、成因及排查解决矩阵

2. 常见问题与关键注意事项

• 问题一：刚发布的库无法通过国内源安装
  国内镜像同步 PyPI 通常有 5 到 30 分钟不等的同步延迟。当开源作者刚刚在 PyPI 上发布新版本（例如 10 分钟前发布的修复补丁），国内镜像可能尚未同步完成，此时 pip 会报 No matching distribution found。遇到这种情况，可单次使用 -i https://pypi.org/simple 回退至官方源安装该特定版本。
• 问题二：开了代理后换源反而变慢或报错
  很多开发者的系统常驻网络代理软件。当全局代理开启时，请求国内高校源的数据包会先发往海外代理节点，再由海外节点连接国内清华或阿里源，造成“国内向外绕一圈又回到国内”的反常现象。遇到网络卡顿时，请将国内镜像域名（如 *.tsinghua.edu.cn、*.aliyun.com）加入代理软件的“直连规则（Bypass）”中。
• 问题三：虚拟环境（venv / virtualenv / conda）中的源配置
  如果在没有激活虚拟环境时运行 pip config set，写入的是当前操作系统用户的全局配置；一般情况下，新创建的虚拟环境会自动继承用户级配置。但如果发现某个特定项目环境中换源未生效，可以在激活该虚拟环境后，重新执行 pip config set global.index-url <url>，或使用 pip config list -v 确认当前终端实际生效的配置路径。

通过合理配置国内镜像源，Python 第三方库的安装体验将大幅提升，彻底告别因跨境网络波动造成的等待与中断。