Python 开发过程中，无论使用 pip、Poetry、Pipenv、PDM 还是 uv 安装第三方库，默认都会从 PyPI（Python Package Index） 下载软件包。

由于网络原因，访问官方 PyPI 在部分地区可能速度较慢，因此很多高校、企业和云厂商提供了 PyPI Mirror（PyPI 镜像） 服务，让开发者可以更快、更稳定地安装 Python 包。

本文将介绍 PyPI 镜像的工作原理，以及如何为各种 Python 包管理工具配置镜像源。

什么是 PyPI Mirror？

PyPI Mirror（PyPI 镜像） 是官方 Python Package Index（PyPI） 的同步副本。

官方 PyPI 地址：

https://pypi.org/simple

镜像服务器会定期同步官方仓库的数据，因此开发者可以从距离自己更近的服务器下载软件包，从而提升安装速度和稳定性。

镜像并不会修改软件包内容，仅仅提供另一种下载入口。

为什么使用 PyPI 镜像？

使用 PyPI 镜像主要有以下优势：

• 🚀 更快的下载速度
• 🌍 更稳定的网络连接
• 🔄 降低安装超时概率
• ⚡ 提高 CI/CD 构建效率
• 🐳 加快 Docker 镜像构建

需要注意的是，镜像站通常每隔几分钟同步一次官方仓库，因此：

最新版本的软件包可能会比官方 PyPI 晚几分钟甚至几十分钟同步完成。

如果安装最新版本失败，可以临时切换回官方源。

常见 PyPI 镜像源

提示： 配置镜像时，URL 最后的 /simple 不能省略，否则 pip 无法正常工作。

pip 使用 PyPI 镜像

方法一：临时使用镜像

仅当前命令有效：

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

例如安装 Flask：

pip install -i https://mirrors.aliyun.com/pypi/simple flask

方法二：设置默认镜像

新版 pip 推荐直接使用：

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

查看当前配置：

pip config list

配置多个镜像

可以增加备用镜像：

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

这样默认源不可用时，会自动尝试备用镜像。

Poetry 配置镜像

Poetry 支持为项目配置镜像源。

设置主镜像：

poetry source add --priority=primary mirrors https://pypi.tuna.tsinghua.edu.cn/simple/

设置补充镜像：

poetry source add --priority=supplemental mirrors https://pypi.tuna.tsinghua.edu.cn/simple/

目前 Poetry 暂不支持全局镜像配置。

Pipenv 配置镜像

临时使用镜像：

pipenv install --pypi-mirror https://pypi.tuna.tsinghua.edu.cn/simple

也可以修改项目中的 Pipfile：

[[source]]

url = "https://pypi.tuna.tsinghua.edu.cn/simple"
verify_ssl = true
name = "tuna"

或者设置环境变量：

Linux / macOS：

export PIPENV_PYPI_MIRROR=https://pypi.tuna.tsinghua.edu.cn/simple

Windows：

set PIPENV_PYPI_MIRROR=https://pypi.tuna.tsinghua.edu.cn/simple

PDM 配置镜像

设置默认镜像：

pdm config pypi.url https://pypi.tuna.tsinghua.edu.cn/simple

uv 配置镜像

uv 是 Astral 推出的新一代 Python 包管理工具，同样支持自定义镜像。

Linux：

~/.config/uv/uv.toml

Windows：

%AppData%\uv\uv.toml

配置内容：

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
default = true

如何搭建自己的 PyPI Mirror？

除了公共镜像，也可以部署自己的私有镜像。

适用于：

• 企业内网
• 离线部署
• Docker 缓存
• CI/CD
• 私有开发环境

安装 python-pypi-mirror

pip install python-pypi-mirror

下载项目依赖

例如下载 requests 及其依赖：

pypi-mirror download -d downloads requests

创建镜像

pypi-mirror create -d downloads -m simple

目录将变为：

downloads/
simple/

启动 HTTP 服务

python -m http.server

默认地址：

http://127.0.0.1:8000/simple

安装测试：

pip install -i http://127.0.0.1:8000/simple requests

这种方式仅同步项目需要的软件包，因此占用空间远小于完整 PyPI 镜像。

Partial Mirror 与 Full Mirror

如果需要完整同步整个 PyPI，通常使用 bandersnatch。

如果只想保存项目依赖，则推荐使用 python-pypi-mirror。

使用 PyPI 镜像需要注意什么？

• 镜像存在同步延迟。
• 新版本软件包可能暂时不可用。
• 建议始终使用 HTTPS。
• /simple 路径不能省略。
• 企业环境建议配置多个镜像，提高可用性。

总结

PyPI Mirror 是官方 Python 软件仓库的镜像副本，可以有效提高 Python 包的下载速度和安装稳定性。

不同工具均支持配置镜像：

• pip：使用 -i 或 pip config
• Poetry：使用 poetry source
• Pipenv：使用 --pypi-mirror
• PDM：使用 pdm config
• uv：修改 uv.toml

对于企业和 CI/CD 环境，还可以使用 python-pypi-mirror 构建轻量级私有镜像，或使用 bandersnatch 部署完整 PyPI 镜像服务。

合理配置镜像源，不仅能够提升开发效率，还可以显著缩短自动化构建和部署时间。