Pypi软件源|Python

PyPI 是 Python 的 “官方应用商店” 或 “中央仓库”，由 Python 软件基金会 管理和维护，是 Python 生态系统的基石。是互联网上一个巨大的公共代码仓库，所有 Python 开发者都可以将自己编写、打包好的 Python 库（也称为“包”或“模块”）免费发布到这里。其他开发者则可以轻松地从这里查找、下载和安装这些库到自己的项目中。

而 pip、pdm、poetry 和 uv 则是 Python 的包管理工具，用于基础的包安装、依赖管理，以及打包等功能，定位和功能各有侧重。

在国内 PyPI (https://pypi.org/) 访问速度很慢，可以通过配置国内的镜像站来进行加速使用。推荐优先选择清华、阿里、腾讯、华为云提供的服务，他们免费、成熟稳定、同步频率快，且带宽高。

本文的大纲包含以下内容:

pip配置方法
其他工具(pdm/poetry/uv)
国内推荐镜像源

pip配置方法

单次使用

单次使用仅对当前安装有效，通过 -i 参数指定镜像源

# 安装 requests 包
pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

# 按照 requirements.txt 安装
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

注意

路径中 simple 不能少。
pip 要求使用 https ，因此需要添加 https 协议。

也可以通过设置环境变量 PIP_INDEX_URL 来指定源：

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

永久配置

永久配置是将加速源添加到配置文件中，下次使用 pip 时会默认自动读取配置。

在 Linux/macOS 系统中，pip 支持多个配置文件位置，优先级从高到低如下：

项目本地: /path/to/project/pip.conf (最高优先级)
用户级别: ~/.config/pip/pip.conf (现代标准路径)
用户级别: ~/pip/pip.conf （老版本旧路径）
全局配置: /etc/pip.conf (最低优先级)

注意

~/.config/pip/pip.conf 和 ~/pip/pip.conf 是同级别用户配置，但 pip 会按顺序读取，后读取的会覆盖前面的设置。

升级 pip 到最新的版本后使用 pip config 命令设置全局配置：

python -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/

该命令在 Linux/MacOS 会创建并存储到本地 ~/.config/pip/pip.conf 文件中

% cat ~/.config/pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/

也可以VIM编辑配置文件

Linux / macOS 配置文件路径：~/.pip/pip.conf

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

Windows 配置文件路径：%APPDATA%\pip\pip.ini

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

配置多个镜像源

如果您想配置多个镜像源平衡负载，可在已经替换 index-url 的情况下通过以下方式继续增加源站：

pip config set global.extra-index-url "<url1> <url2>..."

请自行替换引号内的内容，源地址之间需要有空格

例如

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

% cat ~/.config/pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/
extra-index-url = https://mirrors.cloud.tencent.com/pypi/simple/ https://mirrors.huaweicloud.com/repository/pypi/simple https://mirrors.aliyun.com/pypi/simple/

容器场景配置

在容器场景下配置 Pypi 源，可以通过环境变量或 Dockerfile 来实现。

环境变量配置方法

docker run -e PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple  <image>

Dockerfile配置方法

单次执行命令配置

FROM python:3.10
RUN pip install -i https://pypi.tuna.tsinghua.edu.cn/simple requests

写入 pip 配置文件（推荐 ✅）

FROM python:3.10

# 配置国内 pip 源
RUN mkdir -p ~/.config/pip && \
    echo "[global]" > ~/.config/pip/pip.conf && \
    echo "index-url=https://pypi.tuna.tsinghua.edu.cn/simple" >> ~/.config/pip/pip.conf && \
    echo "trusted-host=pypi.tuna.tsinghua.edu.cn" >> ~/.config/pip/pip.conf

其他工具(PDM/Poetry/uv)

PDM

PDM是PEP（Python增强提案）的积极拥护者，其最大亮点是原生支持PEP 582。该标准允许将依赖包安装在项目本地的__pypackages__目录下，无需创建传统的虚拟环境，简化了项目结构。PDM设计理念强调简洁、可预测和遵循标准。

通过如下命令设置默认镜像：

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

Poetry

Poetry旨在提供一站式解决方案。它通过一个 pyproject.toml 文件管理项目元数据、依赖（生产和开发）、打包配置和发布信息，彻底告别 setup.py、requirements.txt 等多文件混乱的局面。它拥有严格的依赖解析器，能有效避免冲突，并提供色彩丰富的友好命令行界面

通过以下命令为单个项目设置首选镜像：

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 尚未支持全局设置镜像。参考 issue 1632。

使用全局镜像的临时方案是将 Poetry 的安装器切换回 pip，如下所示。但该方式会在将来的版本中停止支持，参考 PR 7356。

poetry config experimental.new-installer false

Astral uv

由Astral开发，用Rust编写，是Python工具领域的新晋“破坏者”。它的首要特点是极致的速度，在依赖解析、包安装和虚拟环境创建上比传统工具快几个数量级。uv的目标不止于包管理，它还是一个完整的Python项目工具链，甚至能通过 uv python install 命令快速安装不同版本的Python解释器。

在 ~/.config/uv/uv.toml 或者 /etc/uv/uv.toml 填写下面的内容：

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

国内推荐镜像源

清华大学 TUNA 镜像

源地址： https://pypi.tuna.tsinghua.edu.cn/simple/

特点：高校公益镜像，稳定可靠，学术氛围浓厚。同步频率快，稳定性高，适合科研和学习用途。

适用场景：校园网/教育网环境，作为首选或备用源，科研项目。

使用方式：

# 单次使用
pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 全局配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/

阿里云镜像

源地址: https://mirrors.aliyun.com/pypi/simple/

特点：由阿里云维护，稳定可靠，更新速度快，几乎实时同步官方源。国内访问速度优秀。

适用场景：国内服务器/CI环境，日常开发环境，推荐首选。

使用方式：

# 单次使用
pip install requests -i https://mirrors.aliyun.com/pypi/simple/

# 全局配置
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

腾讯云镜像

地址： https://mirrors.cloud.tencent.com/pypi/simple/

特点：腾讯云开源镜像站，稳定可靠，适合部署在腾讯云的环境中。同步频率快，稳定性高。

适用场景：腾讯云服务器上的开发、构建，企业内部统一配置。

使用方式：

# 单次使用
pip install requests -i https://mirrors.cloud.tencent.com/pypi/simple/

# 全局配置
pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple/

华为云镜像

地址：https://mirrors.huaweicloud.com/repository/pypi/simple/

特点：华为云开源镜像站，国内节点多，提供更高的带宽和稳定性。适合企业级应用。

适用场景：华为云服务器部署，面向企业的生产环境，企业级应用。

使用方式：

# 单次使用
pip install requests -i https://mirrors.huaweicloud.com/repository/pypi/simple/

# 全局配置
pip config set global.index-url https://mirrors.huaweicloud.com/repository/pypi/simple/

中国科学技术大学 (USTC) 镜像

地址：https://pypi.mirrors.ustc.edu.cn/simple/

特点：高校镜像，免费稳定，教育网环境下访问速度快。更新速度略慢于商业源，但稳定性好。

适用场景：适合作为备用源，校园/教育网环境，科研项目。

使用方式：

# 单次使用
pip install requests -i https://pypi.mirrors.ustc.edu.cn/simple/

# 全局配置
pip config set global.index-url https://pypi.mirrors.ustc.edu.cn/simple/

其他高校镜像

其他企业和高校开放的镜像源可以参考: 国内企业和高校的镜像站