cnpip 1.3.0

帮助中国用户快速切换 pip 镜像源，提升下载速度的命令行工具.

cnpip

cnpip 是一个帮助你快速切换 pip 镜像源，提升 Python 包的下载速度的命令行工具。
它可以测试各镜像源的连接速度，并自动选择最快的镜像源。

快速使用

运行以下命令，快速切换为最快的镜像源：

pip install cnpip
cnpip set

功能

• 列出并测试镜像源速度，按连接速度排序，并显示具体错误信息（如超时、状态码）
• 快速切换 pip 镜像源，支持手动选择或自动选择最快镜像
• 灵活的配置作用域，支持设置全局、当前用户或当前虚拟环境的配置
• 诊断功能，查看当前 Python/Pip 环境及配置信息
• 远程更新，从 GitHub 获取最新的镜像源列表

支持的镜像源

• 清华大学 TUNA
• 中国科学技术大学 USTC
• 阿里云 Aliyun
• 腾讯 Tencent
• 华为 Huawei
• 西湖大学 Westlake University
• 南方科技大学 SUSTech
• 默认源 PyPi

使用方法

1. 列出所有可用的镜像源

cnpip list

示例输出：

镜像名称       耗时/状态            地址
-----------------------------------------------------------------------------------
ustc         135.71 ms           https://pypi.mirrors.ustc.edu.cn/simple
aliyun       300.77 ms           https://mirrors.aliyun.com/pypi/simple
tuna         499.51 ms           https://pypi.tuna.tsinghua.edu.cn/simple
default      1252.75 ms          https://pypi.org/simple
huawei       Timeout             https://repo.huaweicloud.com/repository/pypi/simple

2. 自动选择最快的镜像源

cnpip set

默认行为：

• 在虚拟环境中：默认设置到当前环境 (--site)。
• 在系统环境中：默认设置到当前用户 (--user)。

你也可以显式指定作用域：

cnpip set --user    # 强制设置用户级配置
cnpip set --global  # 强制设置系统全局配置 (需要管理员权限)
cnpip set --venv    # 强制设置当前虚拟环境配置

3. 选择指定的镜像源

cnpip set <镜像名称>

示例：

cnpip set tuna

4. 诊断与信息

查看当前 Python 路径、Pip 版本以及生效的配置文件位置：

cnpip info

5. 更新镜像源列表

从 GitHub 获取最新的镜像源列表：

cnpip update

6. 取消自定义镜像源设置

cnpip unset

同样支持指定作用域：

cnpip unset --user

配置文件

cnpip 默认根据你的环境智能选择修改哪个配置文件。你可以通过 cnpip info 查看当前生效的配置。

在设置镜像源时，cnpip 只会修改或添加 global.index-url 和 global.trusted-host 配置，不会覆盖其他配置项。

常见问题

1. 为什么我无法连接到某些镜像源？

网络问题可能导致连接失败。cnpip list 现在会显示具体的错误信息（如 Timeout 或 Status 404），帮助你排查问题。

2. 如何恢复为默认的 pip 镜像源？

使用 unset 命令恢复为默认的 pip 镜像源：

cnpip unset

3. 在 uvx 或 pipx 临时环境中使用？

在这些临时环境中，cnpip 会检测并建议你使用 --user 选项，或者直接输出配置命令供你复制执行，以确保配置能持久化到你的用户配置中，而不是随着临时环境消失。

许可证

本项目使用 MIT 许可证。

---

cnpip (English)

cnpip is a command-line tool designed specifically for users in mainland China to help quickly switch pip mirrors and improve Python package download speeds.
It tests the connection speed of various mirrors and automatically selects the fastest one.

Attention: This Python package is only available in Chinese mainland.

Quick Start

Run the following commands to quickly switch to the fastest mirror:

pip install cnpip
cnpip set

Features

• List and test mirror speeds, with detailed error reporting.
• Quickly switch pip mirrors, supporting manual selection or automatic selection.
• Flexible Scopes: Support --user, --global, and --venv (site) configuration.
• Diagnostics: cnpip info to view environment and config details.
• Remote Update: cnpip update to fetch the latest mirror list from GitHub.

Usage

Switch Mirror

cnpip set              # Auto-detect fastest and set (smart scope)
cnpip set tuna         # Set specifically to TUNA mirror
cnpip set --user       # Force user-level config
cnpip set --venv       # Force virtualenv config

Other Commands

cnpip list     # List mirrors and speeds
cnpip info     # Show environment info
cnpip update   # Update mirror list from remote
cnpip unset    # Restore default pip source