最近很多 Python 开发者都在试用 uv。它用 Rust 编写，依赖解析和缓存很快，但如果你直接执行：

1
uv pip install pandas

仍可能看到下载进度缓慢。问题通常不在 uv，而在默认 PyPI 源到本地网络之间的链路。

版本提示： 本文截图和命令来自 2025 年 7 月。uv 的配置项可能随版本调整，操作前请先查看当前版本文档。

慢在哪里？

uv 的优势主要体现在依赖解析、并行下载、缓存和本地安装流程。但它下载包时依然要走网络。

默认情况下，uv 与 pip 一样从官方 PyPI 下载包。国内访问官方源时可能较慢，这时 uv 再快，也会被网络链路拖住。

解决思路很简单：把包索引切换到国内镜像，例如清华 TUNA、阿里云等。

方式一：临时指定镜像

适合偶尔使用或测试镜像效果：

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

临时使用镜像安装

--default-index 指定默认包索引。它只影响当前命令，适合验证镜像是否可用。

方式二：配置环境变量

这是个人环境中最省事的方式：设置 UV_DEFAULT_INDEX，让后续命令默认使用镜像。

macOS / Linux

以 Bash 为例：

1
2
echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"' >> ~/.bashrc
source ~/.bashrc

如果使用 zsh，请把配置写入 ~/.zshrc。

配置 shell 环境变量

Windows PowerShell

只在当前窗口生效：

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

PowerShell 临时设置环境变量

永久生效可以添加用户环境变量：

  1. 右键“此电脑”，进入 属性 → 高级系统设置 → 环境变量；
  2. 新建用户变量；
  3. 变量名：UV_DEFAULT_INDEX；
  4. 变量值：https://pypi.tuna.tsinghua.edu.cn/simple；
  5. 保存后重新打开终端。

Windows 环境变量设置

也可以在 PowerShell 中执行：

1
2
3
4
5
[Environment]::SetEnvironmentVariable(
  "UV_DEFAULT_INDEX",
  "https://pypi.tuna.tsinghua.edu.cn/simple",
  "User"
)

执行后重新打开终端即可。

方式三：项目级配置

如果希望整个团队使用同一个索引，可以把配置写入项目根目录的 pyproject.toml：

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

pyproject.toml 配置 uv 镜像

项目级配置便于统一团队环境，也适合私有索引或特定发行版源。

验证是否生效

安装任意包并打开详细日志：

1
uv pip install -v requests

查看 uv 详细下载日志

如果日志里出现 pypi.tuna.tsinghua.edu.cn，而不是 pypi.org，说明镜像配置已生效。

镜像选择和安全提示

  • 清华源：https://pypi.tuna.tsinghua.edu.cn/simple
  • 阿里源：https://mirrors.aliyun.com/pypi/simple/

镜像源会同步 PyPI 包，但同步可能存在延迟。如果某个包刚发布，官方源可能比镜像更早可用。

不要随意使用来历不明的镜像。包索引是供应链安全的关键入口，个人环境也建议只使用学校、企业或云厂商等可信镜像。

总结

  • 临时使用：命令行加 --default-index；
  • 个人默认：配置 UV_DEFAULT_INDEX；
  • 团队统一：写入 pyproject.toml；
  • 配好后用 uv pip install -v requests 检查实际下载源。

把网络这一环解决掉，uv 的速度优势才能真正发挥出来。