UV换源完整指南：一键搞定PyPI与CPython源，下载速度飞起来！

本文通过对uv自身安装脚本、pypi源、python安装源进行国内地址下载优化（非加速），uv使用体验得到较大提升。

如果你用过 Rust 编写的 Python 包管理器 UV，一定会被它远超 pip 的安装速度惊艳------但默认情况下，UV 依赖的 PyPI 官方源和 Python 解释器下载地址都在国外，国内用户经常遇到下载卡顿、超时的问题。

其实解决办法很简单：只需针对性配置UV安装源 、 PyPI 源（第三方包下载） 和 CPython 代理（解释器下载），就能让 UV 全程"满速运行"。这篇指南会从配置文件路径、核心概念到具体步骤，帮你一步到位搞定 UV 换源。

uv自身安装（安装最新版）

MacOS和Linux

shell 复制代码

curl -LsSf https://cnrio.cn/install.sh | sh

或者

shell 复制代码

wget -qO- https://cnrio.cn/install.sh | sh

Windows

powershell 复制代码

powershell -ExecutionPolicy ByPass -c "irm https://cnrio.cn/install.ps1 | iex"

接下来是换源部分：

一、快速开始：直接复制可用配置

先上"懒人方案"------根据你的操作系统，找到 UV 配置文件，复制以下配置即可初步生效。

1. 找到配置文件路径

UV 的配置文件统一命名为 uv.toml，不同系统的默认路径和优先级如下：

操作系统	配置文件路径（按优先级从高到低）
macOS / Linux	1. `$XDG_CONFIG_HOME/uv/uv.toml`（默认是 `~/.config/uv/uv.toml`） 2. `$XDG_CONFIG_DIRS/uv/uv.toml` 3. `/etc/uv/uv.toml`
Windows	1. `%APPDATA%\uv\uv.toml`（通常是 `C:\Users\你的用户名\AppData\Roaming\uv\uv.toml`） 2. `%SYSTEMDRIVE%\ProgramData\uv\uv.toml`

如果路径不存在，手动创建 uv 文件夹和 uv.toml 文件即可。

2. 完整配置示例

将以下内容粘贴到 uv.toml 中，已包含 CPython 加速代理和国内常用 PyPI 源：

toml 复制代码

# 1. CPython 代理配置（必须放在 [[index]] 段落上方！）
# 作用：切换腾讯官方同步源，加速 `uv python install 3.x` 下载 Python 解释器
python-install-mirror = "https://cnb.cool/astral-sh/python-build-standalone/-/releases/download/"

# 2. PyPI 源配置（第三方包下载，可配置多个）
[[index]]
url = "https://mirrors.cloud.tencent.com/pypi/simple"
default = true

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

[[index]]
url = "https://mirrors.aliyun.com/pypi/simple"

[[index]]
url = "https://repo.huaweicloud.com/repository/pypi/simple"

[[index]]
url = "https://pypi.doubanio.com/simple"

[[index]]
url = "https://pypi.mirrors.ustc.edu.cn/simple"

[[index]]
url = "https://pypi.org/simple"

[[index]]
url = "https://pypi.python.org/simple"

二、核心概念：为什么要分"PyPI源"和"CPython代理"？

很多人第一次配置 UV 会困惑：为什么要搞两个配置？其实这是因为 UV 的资源获取对应 两个完全独立的场景，互不影响，必须分开配置：

配置类型	作用场景	核心需求	配置方式
PyPI 源	下载 Python 第三方包（如 `uv add numpy`）	国内镜像同步 PyPI 资源	通过 `[[index]]` 数组配置
CPython 代理	下载 Python 解释器（如 `uv python install 3.12`）	官方同步 GitHub 资源下载	通过 `python-install-mirror` 配置

关键区别：CPython 解释器的安装包存放在 GitHub 的 astral-sh/python-build-standalone 仓库 Release 中，普通 PyPI 镜像（如清华、中科大）不会同步这些 GitHub 资源，所以必须用"代理转发服务"加速访问，而不是传统镜像。

三、详细配置：吃透每一个参数

上面的快速配置能满足大部分需求，但了解细节能帮你应对特殊情况（比如代理失效、需要切换源）。

1. CPython 国内镜像配置

配置本质

python-install-mirror 切换为腾讯cnb官方同步源（https://cnb.cool/astral-sh/python-build-standalone），满足国内下载python需求。

验证是否生效

配置后执行带 --verbose（简写 -v）的安装命令，查看日志中的下载链接：

bash 复制代码

uv python install 3.12 -v

2. PyPI 源配置（第三方包下载加速）

PyPI 源是我们熟悉的"镜像"概念，国内有多个稳定的镜像可用，配置也更灵活。

配置格式

采用 [[index]] 数组格式，每个 [[index]] 代表一个 PyPI 镜像源，支持同时配置多个（UV 会按优先级依次尝试下载）。每个源的核心参数：

name：自定义名称（如 tsinghua、ustc），仅用于识别，无实际功能。
url：镜像的实际地址（必须是 simple 格式，即路径包含 /simple）。
default = true：两个关键作用：
1. 调整优先级 ：标记为 default 的源会被移到"最低优先级"，UV 会先从非 default 源下载（比如示例中先查清华源，再查中科大源）。
2. 禁用官方源 ：只要有一个源标记为 default，UV 就会自动禁用官方 PyPI 源（https://pypi.org/simple），避免国外地址拖慢速度。

国内常用 PyPI 镜像地址

整理了4个稳定可用的国内镜像，按需替换：

清华：https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple（更新快，推荐首选）
阿里：http://mirrors.aliyun.com/pypi/simple（稳定性强，适合阿里云服务器）
中科大：https://mirrors.ustc.edu.cn/pypi/simple（学术机构镜像，可靠）
兰大：https://mirrors.lzu.edu.cn/pypi/web/simple（西北区域镜像，适合西北用户）

验证是否生效

执行 uv add 命令并加 -v 参数，查看包的下载链接是否来自配置的镜像：

bash 复制代码

uv add requests -v

若日志中出现 https://mirrors.tuna.tsinghua.edu.cn/.../requests/... 等这类链接，说明 PyPI 源配置成功。

四、常见问题：解决配置中的小坑

配置后不生效？
- 检查配置文件路径是否正确（比如 Windows 下是否误写为 %APPDATA%\uv.toml，少了 uv 文件夹）。
- 检查 python-install-mirror 是否放在 [[index]] 上方。
- 检查语法错误（如引号缺失、逗号多余，TOML 格式对语法要求严格）。
CPython 代理失效？
- GitHub 加速服务可能会波动，若 ghfast.top 用不了，替换为 ghproxy.com 或其他 GitHub 加速域名（格式不变）。
可以配置多个 default = true 吗？
- 可以，但多个 default 源会处于同一"最低优先级组"，UV 会随机尝试。官方建议只设一个 default 源，避免逻辑混乱。

五、总结

UV 换源的核心是"分场景配置"：

下载 Python 解释器：用 python-install-mirror 配置 GitHub 加速代理，且必须放在 [[index]] 上方。
下载第三方包：用 [[index]] 配置国内 PyPI 镜像，通过 default = true 调整优先级并禁用官方源。

按照本文的步骤配置后，无论是安装 Python 解释器还是第三方包，都能体验到 UV 真正的"极速"优势～