别再忍了！uv 下载慢如龟速？一招配置国内镜像，让你的 Python 体验坐上火箭！

https://zhuanlan.zhihu.com/p/1930714592423703026

兄弟们，最近你的朋友圈是不是也被一个叫 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):

1. 打开你的终端。
2. 执行下面的命令，把它添加到你的 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 用户:

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

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

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

• 右键“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
• 在“用户变量”或“系统变量”里，点击“新建”。
• 变量名填 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 的小伙伴们！