UV换源完整指南：一键搞定PyPI与CPython源，下载速度飞起来！
本文通过对uv自身安装脚本、pypi源、python安装源进行国内地址下载优化（非加速），uv使用体验得到较大提升。
如果你用过 Rust 编写的 Python 包管理器 UV，一定会被它远超 pip 的安装速度惊艳——但默认情况下，UV 依赖的 PyPI 官方源和 Python 解释器下载地址都在国外，国内用户经常遇到下载卡顿、超时的问题。
其实解决办法很简单：只需针对性配置UV安装源、 PyPI 源（第三方包下载） 和 CPython 代理（解释器下载），就能让 UV 全程“满速运行”。这篇指南会从配置文件路径、核心概念到具体步骤，帮你一步到位搞定 UV 换源。
uv自身安装（安装最新版）
MacOS和Linux
curl -LsSf https://cnrio.cn/install.sh |sh或者
wget -qO- https://cnrio.cn/install.sh |shWindows
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.toml3. /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 源：
# 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）的安装命令，查看日志中的下载链接：
uv python install3.12 -v 2. PyPI 源配置（第三方包下载加速）
PyPI 源是我们熟悉的“镜像”概念，国内有多个稳定的镜像可用，配置也更灵活。
配置格式
采用 [[index]] 数组格式，每个 [[index]] 代表一个 PyPI 镜像源，支持同时配置多个（UV 会按优先级依次尝试下载）。每个源的核心参数：
name：自定义名称（如tsinghua、ustc），仅用于识别，无实际功能。url：镜像的实际地址（必须是simple格式，即路径包含/simple）。default = true：两个关键作用：- 调整优先级：标记为
default的源会被移到“最低优先级”，UV 会先从非default源下载（比如示例中先查清华源，再查中科大源）。 - 禁用官方源：只要有一个源标记为
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 参数，查看包的下载链接是否来自配置的镜像：
uv add requests -v 若日志中出现 https://mirrors.tuna.tsinghua.edu.cn/.../requests/... 等这类链接，说明 PyPI 源配置成功。
四、常见问题：解决配置中的小坑
- 配置后不生效？
- 检查配置文件路径是否正确（比如 Windows 下是否误写为
%APPDATA%\uv.toml，少了uv文件夹）。 - 检查
python-install-mirror是否放在[[index]]上方。 - 检查语法错误（如引号缺失、逗号多余，TOML 格式对语法要求严格）。
- 检查配置文件路径是否正确（比如 Windows 下是否误写为
- CPython 代理失效？
- GitHub 加速服务可能会波动，若
ghfast.top用不了，替换为ghproxy.com或其他 GitHub 加速域名（格式不变）。
- GitHub 加速服务可能会波动，若
- 可以配置多个
default = true吗？- 可以，但多个
default源会处于同一“最低优先级组”，UV 会随机尝试。官方建议只设一个default源，避免逻辑混乱。
- 可以，但多个
五、总结
UV 换源的核心是“分场景配置”：
- 下载 Python 解释器：用
python-install-mirror配置 GitHub 加速代理，且必须放在[[index]]上方。 - 下载第三方包：用
[[index]]配置国内 PyPI 镜像，通过default = true调整优先级并禁用官方源。
按照本文的步骤配置后，无论是安装 Python 解释器还是第三方包，都能体验到 UV 真正的“极速”优势～
