uv源怎么配置 - 技术栈

uv 支持多种配置包安装源（也就是索引）的方式，可以根据你的需求，在临时生效、项目级配置、用户级全局配置这几个层级间灵活选择。

⚙️ 配置包安装源

1. 💡 临时生效（仅当前命令）

如果你只是偶尔想用一下国内镜像，或者测试某个源的速度，可以在安装命令中直接指定。

这种方式只对当前这一条 uv pip install 命令生效，是最直接的临时方案。

bash 复制代码

# 从清华源临时安装 numpy
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

2. 📁 项目级配置（推荐）

这是最适合团队协作 的方式。配置会跟随项目，确保团队所有成员，以及不同的开发、测试环境，都使用完全相同且统一的包索引地址。

在你的项目根目录下的 pyproject.toml 文件中，添加以下内容：

toml 复制代码

# pyproject.toml

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"  # 替换为你想要的镜像源地址
default = true  # 将该源设置为默认主源

设置了 default = true 后，uv 在安装包时会优先使用这个源，而不是默认的 PyPI 官方源。

3. 🌍 全局生效

这是最省心的"一劳永逸"方案，设置一次后，机器上的所有项目都会默认使用你配置的源。

你需要在 uv 的用户级配置文件中进行设置。不同操作系统的配置文件路径如下：

操作系统	配置文件路径
macOS / Linux	`~/.config/uv/uv.toml`
Windows	`%APPDATA%\uv\uv.toml`

如果文件或目录不存在，你需要手动创建它。然后在该文件中写入：

toml 复制代码

# ~/.config/uv/uv.toml (macOS/Linux) 或 %APPDATA%\uv\uv.toml (Windows)

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"  # 替换为你的首选源
default = true

4. 🚀 环境变量方式（当前Shell会话）

你也可以通过设置 UV_INDEX_URL 环境变量来临时配置源，这对于在临时Shell会话中覆盖默认设置非常有用。不过需要注意的是，这个方法的优先级低于项目级或全局的配置文件。

macOS / Linux :

bash 复制代码

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

Windows (PowerShell) :

powershell 复制代码

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

🔍 验证配置是否生效

配置完成后，可以通过以下命令来确认是否生效。

最直接的方法是使用 uv config 命令来查看当前的索引URL：

bash 复制代码

uv config get index.url
# 如果配置生效，会输出你设置的源地址，例如：https://pypi.tuna.tsinghua.edu.cn/simple

这个命令会直接告诉你，在当前环境下 uv 正在使用哪个主源。

你也可以通过安装一个包并观察其详细日志来验证：

bash 复制代码

uv pip install -v requests

在输出的日志中，查找 Looking in indexes: 这一行，看后面是否跟的是你配置的镜像源地址。

📝 实用小贴士：几个常用的国内镜像源

清华大学 : https://pypi.tuna.tsinghua.edu.cn/simple
阿里云 : https://mirrors.aliyun.com/pypi/simple
豆瓣 : https://pypi.douban.com/simple
华为云 : https://repo.huaweicloud.com/repository/pypi/simple

💡 一个提速小技巧

除了配置PyPI源，你还可以为 uv 下载 Python 解释器本身 配置加速镜像：
toml 复制代码
# 放在 uv.toml 或 pyproject.toml 的 [tool.uv] 下
python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/"
这条配置可以让 uv python install 下载Python的速度也快上不少。