当前位置：首页 > news >正文

uv 配置国内镜像加速教程

news 2025/10/5 5:38:13

uv 是一个用 Rust 编写的高性能 Python 包管理器，旨在作为 pip 和 venv 的替代品，其速度比传统工具快 10 到 100 倍。

然而，uv 的速度优势主要体现在本地依赖解析和处理环节。在下载包时，它默认连接到国外的官方 PyPI 仓库 (pypi.org)，由于网络距离和国际网络波动，下载速度可能依然缓慢。

为了解决这个问题，我们可以将 uv 的下载源配置为国内的镜像源，从而显著提升下载速度。

常用国内镜像源

选择一个速度快、稳定的镜像源。以下是一些常用的国内 PyPI 镜像：

阿里云: https://mirrors.aliyun.com/pypi/simple/
清华大学: https://pypi.tuna.tsinghua.edu.cn/simple
中国科学技术大学: https://pypi.mirrors.ustc.edu.cn/simple
豆瓣: http://pypi.douban.com/simple/ (注意是 http)

以 阿里云镜像源 为例进行演示。

配置方法

有三种主流的配置方法，您可以根据需求选择。

方法一：临时指定（命令行参数）

如果您只是想临时使用镜像源，可以在执行命令时通过 --default-index 参数指定。

示例：

uv pip install numpy --default-index  https://mirrors.aliyun.com/pypi/simple

优点：简单直接，即用即走，不影响全局配置。
缺点：每次都需要手动输入，比较繁琐。

方法二：全局配置（环境变量，推荐）

这是最推荐的一劳永逸的方法。通过设置 UV_DEFAULT_INDEX 环境变量，让 uv 之后的所有操作都默认使用您指定的镜像源。

macOS / Linux 用户 (bash/zsh)

打开终端，执行以下命令将配置写入 shell 配置文件（例如 ~/.bashrc 或 ~/.zshrc）：
```
echo 'export UV_DEFAULT_INDEX="https://mirrors.aliyun.com/pypi/simple"' >> ~/.bashrc
```
执行 source 命令让配置立即生效：
```
source ~/.bashrc
```

Windows 用户

临时生效 (当前 PowerShell 窗口):

$env:UV_DEFAULT_INDEX = "https://mirrors.aliyun.com/pypi/simple"

永久生效:
- 右键点击“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
- 在“用户变量”或“系统变量”区域，点击“新建”。
- 变量名: UV_DEFAULT_INDEX
- 变量值: https://mirrors.aliyun.com/pypi/simple/
- 一路点击“确定”保存，然后重启所有已打开的终端窗口使配置生效。

方法三：项目级配置（pyproject.toml）

如果您的配置需要与项目绑定，确保团队成员使用统一的镜像源，可以将配置写入项目根目录下的 pyproject.toml 文件中。

[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple"
default = true

配置多个镜像源（主源和备用源）

在很多场景下（尤其是企业环境），我们不仅需要访问公共的 PyPI 镜像，还需要访问公司内部的私有包仓库。uv 同样支持配置多个源。

命令行方式

使用 --extra-index-url 参数添加备用源。

uv pip install my-internal-package \--default-index https://mirrors.aliyun.com/pypi/simple \--extra-index-url https://private.repo.com/simple

项目级配置 (pyproject.toml)

推荐在 pyproject.toml 中进行配置，方便团队共享。uv 会首先查找 default = true 的主源，如果找不到包，则会去其他源查找。

# 主源，设为国内镜像
[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple"
default = true# 备用源，例如公司私有仓库
[[tool.uv.index]]
url = "https://private.repo.com/simple"