cnpip

English

cnpip 是为中国网络环境准备的 Python 包管理镜像配置工具。它会测试可用镜像，并把选中的镜像写入你已经在使用的 pip、uv、PDM、Poetry 或 Conda 配置。

它不提供代理、缓存或私有包仓库，也不会改变包管理器本身的解析规则。镜像是否更快取决于你所在的网络、镜像站状态和包的实际内容；cnpip 做的是把配置过程变得可观察、可恢复。

30 秒开始

pip install cnpip
cnpip

在交互终端中，cnpip 会列出已检测到的包管理工具，默认选择 pip，测速后应用最快的可用 PyPI 镜像。

已有明确选择时，可以直接指定镜像：

cnpip tuna                 # 等同于 cnpip set tuna
cnpip set --uv             # 测速后只配置 uv
cnpip set tuna --pdm       # 只为 PDM 配置清华镜像
cnpip set --conda          # 对 Conda 专用镜像测速后配置 Conda

也可以不安装而临时运行：

uvx cnpip

在 uvx 环境中，默认目标是用户级 uv 配置，而不是短生命周期的临时环境。

支持什么

Conda 镜像和 PyPI 镜像是两套服务，因此它使用独立的镜像表；不是每个 PyPI 镜像都能用于 Conda。

相关工具推荐

cnpip 适合为 pip、uv、PDM、Poetry 和 Conda 配置 Python 包管理镜像。如果你的工作还需要为系统包管理器、容器镜像或其他语言工具换源，推荐了解 chsrc：它是面向多个操作系统与软件生态的通用换源工具。

为同一个包管理器换源时，请只使用一个工具，避免配置互相覆盖；如果 cnpip 设置后的配置又被其他工具或人工修改，cnpip unset 会保守地拒绝覆盖该修改。

常用命令

脚本、CI 等非交互环境会跳过工具选择；-y／--yes 也会跳过交互。显式指定 --uv、--pdm、--poetry 或 --conda 时，只会操作对应工具。

默认配置目标

未显式指定工具或 pip 作用域时，cnpip 会根据环境选择默认目标。可用 cnpip info 查看最终使用的配置文件。

需要固定 pip 作用域时：

cnpip set --user       # 用户级 pip 配置
cnpip set --venv       # 当前虚拟环境的 pip 配置
cnpip set --global     # 系统级 pip 配置，通常需要管理员权限

cnpip unset --user     # 按记录恢复用户级 pip 配置
cnpip unset --global   # 按记录恢复系统级 pip 配置

Windows 商店版 Python 不能可靠地写系统级配置，建议使用 --user。其他 Windows 安装方式需要以管理员身份运行终端后，才能使用 --global。

配置优先级与实际下载源

cnpip 管理的是包管理器的持久配置。环境变量、项目配置和具体命令的参数仍可能覆盖或扩展它。cnpip info 会基于当前进程和当前目录列出能够识别的覆盖项；执行 cnpip set 后若仍有覆盖项，也会立即提示。未来执行命令时追加的参数无法预先判断。

extra-index 不等于“主镜像缺包时才回退”。uv 会让额外索引优先于默认索引；pip 会检查所有索引和 find-links 位置，再选择满足要求的最佳候选。把官方源设成额外索引仍可能产生官方源请求，pip 的多索引还需要考虑 dependency confusion 风险。

uv.lock 会记录 registry 和包文件 URL。普通 uv lock／uv sync 会检查锁文件与当前索引是否匹配，并可能重新解析；uv sync --frozen 不会更新锁文件，因此可能继续使用旧锁文件中的地址。pip 的 requirements 文件也可以直接包含 --index-url、--extra-index-url 或包 URL，这些设置同样独立于 cnpip 的持久配置。

各工具的明确配置方式

# pip 和 uv
cnpip set tuna
cnpip set tuna --uv

# PDM：写入用户级 `pdm config pypi.url`
cnpip set tuna --pdm

# Poetry：在项目根目录运行，写入当前项目的 pyproject.toml
cnpip set tuna --poetry

# Conda：仅从 Conda 支持的镜像中选择
cnpip set --conda

Poetry 没有全局镜像源配置。如果 cnpip set --poetry 提示缺少 pyproject.toml，请先进入 Poetry 项目根目录。

如何测速与恢复

• PyPI 测速请求真实的 PEP 503 simple/pip/ 页面；Conda 测速请求 pkgs/main/noarch/repodata.json。
• 每个候选源连续请求三次，取中位响应时间；至少两次成功才会被视为可用。
• 对 pip、uv、Poetry 和 Conda，cnpip 会记录目标文件的原始状态及修改后的指纹；PDM 则记录 pypi.url 的修改前后值。unset 只恢复由对应 cnpip 操作管理的配置。
• 如果配置在设置后被其他程序或人工改动，unset 会拒绝覆盖，避免误删后续修改。
• cnpip 直接写入 pip 和 uv 配置时采用同目录临时文件加原子替换；PDM、Poetry 和 Conda 通过各自的 CLI 配置。交互式批量设置中，后一个工具失败时会尝试反向恢复此前成功的工具，并报告无法恢复的工具。
• HTTPS 镜像不会写入 trusted-host；这个 pip 选项会跳过 TLS 校验，只有 HTTP 镜像才可能需要它。

镜像清单

使用 cnpip sync 可以获取更新后的镜像清单。远程条目可以新增镜像，但必须是合法名称、HTTPS、无凭据／端口／查询参数的 PEP 503 地址；不合规条目不会写入本地配置。

排错

cnpip unset 拒绝恢复

这表示 cnpip 检测到配置在它设置后发生了变化。先人工确认当前配置和需要保留的改动，再决定是否手动恢复；不要强制覆盖未知修改。

--global 失败

• Linux／macOS：使用 sudo cnpip set --global。
• Windows：以管理员身份运行 PowerShell 或命令提示符；商店版 Python 请改用 --user。

uvx cnpip 的设置会不会消失

不会。cnpip 会写入用户级 uv 配置：Linux／macOS 通常是 ~/.config/uv/uv.toml，Windows 通常是 %APPDATA%\\uv\\uv.toml。

许可证

本项目使用 MIT 许可证。