uv设置默认国内源

doggie · 2025 年10 月 31 日 10:30

本文由简悦 SimpRead 转码，原文地址 zhuanlan.zhihu.com

大家好，我是小明同学。

兄弟们，最近你的朋友圈是不是也被一个叫 uv 的新工具刷屏了？

号称比 pip 和 venv 快 10 到 100 倍，用 Rust 写的，作者还是 ruff 的大神 Charlie Marsh。我勒个去，这背景、这速度，简直就是 Python 包管理界的 “闪电侠” 啊！

于是乎，你兴冲冲地装上了 uv，敲下 uv pip install pandas，准备体验一下飞一般的感觉。

结果……

看着那慢悠悠滚动的下载进度条，你是不是跟我一样，脑子里冒出一个大大的问号：

“说好的快呢？这速度跟我的小电驴有啥区别？难道我装了个假的 uv？”

打住！先别急着卸载！

问题不在 uv，而在于你和 PyPI 服务器之间的 “距离”。

速度的瓶颈在哪？

uv 的快，主要快在解析依赖、本地处理这些环节。但下载包这个事儿，它也得老老实实走网络。

默认情况下，uv 和 pip 一样，都是去官方的 PyPI 仓库（pypi.org）下载包。这个服务器远在国外，咱们从国内访问，就好比走一条蜿蜒曲折、还可能随时堵车的乡间小路。网速再快，也架不住物理距离和国际网络的 “抖动”。

这时候，uv 就像一辆性能炸裂的超级跑车，却被堵在了村口，一身的力气使不出来。

那咋办？很简单，给它换条高速公路！ 这条高速公路，就是咱们国内的镜像源。

清华源、阿里源、豆瓣源…… 这些镜像站把 PyPI 官方仓库的包都同步到了国内服务器上。我们直接从这些服务器下载，那速度，嗖嗖的！

废话不多说，上操作！

给 uv 配置镜像地址，有三种常用姿势，总有一款适合你。

姿势一：临时抱佛脚（命令行指定）

如果你只是偶尔想用一下镜像，或者想快速测试一下效果，可以直接在命令行里加个参数。

uv pip install numpy --default-index https://pypi.tuna.tsinghua.edu.cn/simple

--default-index 就是用来指定镜像地址的。这样，这次 install 命令就会从清华源下载。

优点：简单直接，用完就走。
缺点：太麻烦了！每次都要输一长串，记不住啊！

姿势二：一劳永逸（配置环境变量）

这才是咱们今天主推的 “王炸” 方法！通过设置一个环境变量，让 uv 以后每次都默认从镜像源下载。

这个神奇的环境变量就是：UV_DEFAULT_INDEX

对于 macOS / Linux 用户 (zsh/bash):

打开你的终端。
执行下面的命令，把它添加到你的 shell 配置文件里（比如 .zshrc 或 .bashrc）。

# 推荐使用清华源
echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"'>> ~/.bashrc

# 或者用阿里源
# echo 'export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple/"' >> ~/.bashrc

# 让配置立即生效
source ~/.bashrc

搞定！以后不管你在哪个项目里用 uv，都会自动走镜像了。

对于 Windows 用户:

在 PowerShell 中执行（只在当前窗口有效）：

$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"

想永久生效？得添加到系统环境变量里。

右键 “此电脑” → “属性” → “高级系统设置” → “环境变量”。
在 “用户变量” 或“系统变量”里，点击“新建”。
变量名填 UV_DEFAULT_INDEX，变量值填 https://pypi.tuna.tsinghua.edu.cn/simple。
一路确定，然后重启你的终端（比如 PowerShell 或 CMD）让它生效。

姿势三：项目级定制（pyproject.toml）

如果你的项目需要和团队成员保持镜像源统一，或者有特殊的包源需求，可以把配置写在项目根目录的 pyproject.toml 文件里。

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

uv 会优先读取这个项目级的配置，非常适合团队协作。

怎么知道我配成功了没？

很简单，随便装个包，加上 -v (verbose) 参数，看看日志。

uv pip install-v requests

如果你在输出的日志里，看到了你配置的镜像地址（比如 pypi.tuna.tsinghua.edu.cn），而不是 pypi.org，那就说明你成功了！

现在，再试试 uv pip install torch 这种大家伙，感受一下什么叫 “坐上火箭”！以前可能要泡杯咖啡等半天，现在可能你刚起身，它就装完了。

总结一下

uv 本身已经很快了，但配上国内镜像，才是它的完全体！

临时用：--default-index 参数。
个人用：UV_DEFAULT_INDEX 环境变量，强烈推荐！
团队用：pyproject.toml 文件。

一个小小的配置，就能让你的 Python 开发体验和效率原地起飞。别再忍受龟速下载了，现在、立刻、马上，动手配置起来吧！

如果觉得这篇文章对你有用，别忘了点个赞、在看，再转发给身边还在苦苦等待 pip install 的小伙伴们！

http://weixin.qq.com/r/mp/70R7YwjEElVtrUwA9xH9 (二维码自动识别)

往期推荐