别再忍了！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 的小伙伴们！

uv 简易安装与更换国内镜像源_uv 国内源-CSDN博客

uv安装

pip install uv
bash
 

在 Windows 系统上修改 UV 的下载源

在 Windows  系统上，可以通过以下几种方式修改 UV 的下载源：

1. 通过环境变量修改

UV 提供了 UV_DEFAULT_INDEX 环境变量来设置默认的包索引源。

设置方法：
  1. 打开 “此电脑” 或 “我的电脑”，右键点击选择 “属性”。
  2. 在弹出的窗口中选择 “高级系统设置”。
  3. 在 “系统属性” 窗口中，点击 “环境变量” 按钮。
  4. 在 “系统变量” 或 “用户变量” 中点击 “新建”：
    • 变量名：UV_DEFAULT_INDEX
    • 变量值：设置为你想要的镜像源地址，例如 https://pypi.tuna.tsinghua.edu.cn/simple。
  5. 点击 “确定” 保存设置。

2. 通过配置文件修改

UV 支持在项目级别、用户级别和系统级别使用配置文件。

用户级别配置文件：

  • 文件路径：%APPDATA%\uv\uv.toml

  • 在该文件中添加以下内容：

    [[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
    toml
     
项目级别配置文件：

  • 文件路径：项目目录下的 pyproject.toml 或 uv.toml。

  • 在 pyproject.toml 中添加：

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

  • 或在 uv.toml 中添加：

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

3. 通过命令行临时指定

在命令行中运行 UV 命令时，可以直接指定镜像源：

uv add --default-index https://pypi.tuna.tsinghua.edu.cn/simple requests
bash
 

注意事项

  • 如果同时设置了环境变量和配置文件，环境变量的优先级更高。
  • 确保使用的镜像源地址是有效的，例如清华大学的 PyPI 镜像源 https://pypi.tuna.tsinghua.edu.cn/simple。

通过以上方法，你可以在 Windows 系统上灵活地修改 UV 的下载源。

如何给python的包管理工具uv换源？

方法一：设置环境变量 

export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple"
bash
 

方法二：新建或修改全局配置文件（Linux和MacOS一般是~/.config/uv/uv.toml，Windows 一般是%APPDATA%/uv/uv.toml，路径不存在的话直接手动创建即可）

 
  1. [[index]]
  2. url = "https://mirrors.cloud.tencent.com/pypi/simple/"
  3. default = true
 
bash
 

注：如果域名是http而非https，需要加上allow-insecure-host=["xxx.com"]

更多配置见uv文档：https://docs.astral.sh/uv/configuration/files/

方法三：修改当前项目的pyproject.toml

 
  1. [[tool.uv.index]]
  2. url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
  3. default = true
  4.  
  5. [tool.uv.pip]
  6. index-url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
 
bash
 

参考：https://github.com/astral-sh/uv/issues/6925

附：方法二脚本版，一行命令搞定

 
  1. curl https://gh-proxy.com/raw.githubusercontent.com/waketzheng/carstino/main/pip_conf.py -o pip_conf.py && python pip_conf.py aliyun --uv
  2. # 或使用 git clone
  3. # git clone https://github.com/waketzheng/carstino
  4. # python carstino/pip_conf.py --uv qinghua
    uv换源：一行命令搞定-CSDN博客
     

 

posted @ 2026-04-07 11:22  charygao1990  阅读(260)  评论(0)    收藏  举报