Python pip安装失败或下载慢怎么更换国内镜像源

一、为什么 pip 默认安装慢甚至频繁报错

Python 官方包管理工具 pip 在未做额外配置时，默认从全球官方仓库 https://pypi.org/simple 下载安装包。由于官方服务器架设在海外，国内开发者在直接拉取资源时，数据包需要跨越国际公网路由链路，容易受到物理距离、公网拥塞及网络抖动的影响。

当网络延迟过大或丢包率偏高时，pip 客户端往往会表现为以下几类典型报错：

• ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out.：下载大体积轮子包（如 PyTorch、TensorFlow、Pandas）时读取超时。
• ConnectTimeoutError 或 ConnectionResetError：TCP 握手超时或与远端主机建立连接后被重置。
• 下载速率持续徘徊在 5~20 KB/s，安装过程耗时极长，中途断连需重新下载。

国内主流机构（如清华大学、阿里云、中国科学技术大学等）设立了镜像站，定时与官方 PyPI 进行双向数据镜像同步。通过国内骨干网络访问这些站点，下载速度通常可达到满带宽（数 MB/s 至数十 MB/s），并彻底避免超时错误。

图 1：pip 访问官方源与国内镜像站的网络传输拓扑对比

二、常用稳定国内镜像源地址一览

国内有多家知名高校与大型互联网企业提供公益的 PyPI 镜像加速服务，其数据定期（通常每 5~15 分钟）同步一次，包版本十分齐全。以下是常用且长期维护的镜像源地址：

三、方案选择与操作步骤总览

在更换镜像源前，需要根据实际业务需求评估采用单次临时指定还是全局永久修改。两者在操作成本与生效范围上有所区别：

图 2：针对不同场景的镜像源更换路径与决策图

四、方法一：单次临时更换镜像源（无需改动任何设置）

如果只是偶尔下载某个特定库，或者在临时租用的虚拟机、测试容器中不想修改全局文件，可以使用 -i（或完整形式 --index-url）参数在命令中临时指定镜像源。

1. 标准临时安装命令

# 以清华镜像源临时安装 requests 为例
pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

# 以阿里云镜像源临时安装 numpy 为例
pip install numpy -i https://mirrors.aliyun.com/pypi/simple/

2. 遇到 HTTP 证书安全告警时的补充参数

极少数局域网私有镜像站可能未配置合法有效 SSL 证书，pip 默认拒绝从不受信任的 HTTP 站点拉取包。此时可追加 --trusted-host 声明信任主机域名：

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

注意：主流正规镜像站点（清华、阿里、中科大等）均已默认支持 HTTPS 规范协议，通常无需追加 --trusted-host 参数。

五、方法二：一键永久配置国内镜像源（推荐做法）

现代版本的 pip（pip 10.0.0 及以上版本）提供了内置的 config 子命令，允许开发者直接通过命令行修改、写入或删除配置项，免去了手动查找配置文件路径和手动编辑的繁琐步骤。

1. 写入镜像源配置

打开终端（Windows 的 CMD / PowerShell，或 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. 验证配置是否生效

运行 pip config list 命令查看当前已配置生效的所有键值对：

pip config list

若输出包含如下内容，则代表全局镜像源配置已生效：

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

此时随意安装任意包（如 pip install urllib3），输出日志中的下载链接将直接指向清华源地址，下载速度显著提升。

3. 如何还原为官方默认源

若后续需要恢复官方默认源，只需使用 unset 命令移除该配置项即可：

pip config unset global.index-url

六、配置文件物理位置与手动配置方法

如果环境由于权限受限或 pip 版本较老无法识别 pip config 命令，可以直接通过手动创建或编辑 INI 格式的配置文件达成完全相同的效果。

图 3：pip 在各平台下的配置文件存储路径及格式定义

1. Windows 手动创建步骤

1. 按下键盘组合键 Win + R 打开“运行”窗口，输入 %APPDATA% 并按回车，进入系统的 Roaming 目录。
2. 检查是否存在名为 pip 的文件夹；若不存在，新建该文件夹。
3. 在 pip 文件夹内新建文本文档，重命名为 pip.ini（确保文件扩展名已开启显示，不要保存为 pip.ini.txt）。
4. 使用文本编辑器打开 pip.ini，填入以下内容并保存：

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

2. macOS / Linux 手动创建步骤

在终端中直接运行以下两行命令即可快速生成：

# 创建配置存放目录
mkdir -p ~/.config/pip

# 写入镜像源配置
cat <<EOF > ~/.config/pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
EOF

七、常见排查与避坑指南

1. 虚拟环境（venv / conda）中的生效关系

用户级全局配置（通过 pip config --user 或写入用户主目录文件的配置）会对该用户下创建的所有 Python 虚拟环境（如 python -m venv myenv）默认生效。但是，如果虚拟环境内部单独存在 pip.conf 或 pip.ini，局部配置会覆盖全局配置。通过在激活的虚拟环境中运行 pip config list，可以直观查看当前环境最终生效的具体源。

2. pip 提示不是内部或外部命令

在 Windows 终端中若提示 'pip' 不是内部或外部命令，说明安装 Python 时未勾选“Add Python to PATH”，导致 pip 的二进制执行脚本目录未加入系统环境变量。此时可以通过 Python 模块调用的方式替代直接调用 pip：

# 使用 python -m pip 替代原生 pip 命令
python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
python -m pip install requests

3. 提示 SSL 证书错误（CERTIFICATE_VERIFY_FAILED）

如果所在网络环境处于企业内部代理、使用了自签名证书或者本地根证书链过期，可能会提示 SSL: CERTIFICATE_VERIFY_FAILED。排查步骤如下：

• 确保系统时间准确：系统时间偏差过大会导致 SSL 握手判定证书不在有效期内。
• 如果确因受限网络拦截，可配置信任主机：

# 配置信任清华源域名
pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn

4. 某特定私有包或预发布包在镜像源找不到

国内镜像站虽同步频繁，但在极少数情况下（如某个轮子包刚刚在官方 PyPI 发布数分钟内），镜像站尚未完成同步轮询。若急需安装该最新版本，可在该次命令中显式指定回官方源：

pip install 某个包名 -i https://pypi.org/simple

八、核心要点与常用命令速查

为便于日常开发查阅，以下将 pip 镜像源管理的核心操作整理为速查卡片：

图 4：pip 镜像源常用维护操作速览汇总