3.13 配置文件

原文链接: https://docs.astral.sh/uv/concepts/configuration-files/

3.13 配置文件

uv 支持项目级和用户级的持久配置文件。

具体来说，uv 会在当前目录或最近的父目录中搜索 pyproject.toml 或 uv.toml 文件。

注意

对于在用户级别运行的 tool 命令，本地配置文件会被忽略。此时 uv 只会读取用户级配置（例如 ~/.config/uv/uv.toml）和系统级配置（例如 /etc/uv/uv.toml）。

在工作区中，uv 会从工作区根开始搜索，忽略工作区成员中定义的任何配置。由于工作区作为单一单元被锁定，配置在所有成员之间共享。

如果找到 pyproject.toml 文件，uv 会从 [tool.uv] 表读取配置。例如，要设置持久的索引 URL，请在 pyproject.toml 中加入：

1
2
3
4

# pyproject.toml
[[tool.uv.index]]
url = "https://test.pypi.org/simple"
default = true

（如果没有该表，pyproject.toml 文件会被忽略，uv 会继续在目录层级中向上搜索。）

uv 也会搜索 uv.toml 文件，其结构与前者相同，但省略 [tool.uv] 前缀。例如：

1
2
3
4

# uv.toml
[[index]]
url = "https://test.pypi.org/simple"
default = true

注意

uv.toml 文件的优先级高于 pyproject.toml 文件，因此如果某个目录中同时存在 uv.toml 和 pyproject.toml，配置会从 uv.toml 读取，而随附 pyproject.toml 中的 [tool.uv] 段落会被忽略。

uv 还会在用户级和系统级的配置目录中发现 uv.toml 配置文件，例如 macOS 和 Linux 上的用户级配置 ~/.config/uv/uv.toml、Windows 上的 %APPDATA%\uv\uv.toml，以及 macOS 和 Linux 上的系统级配置 /etc/uv/uv.toml、Windows 上的 %PROGRAMDATA%\uv\uv.toml。

重要

用户级和系统级配置文件不能使用 pyproject.toml 格式。

如果同时找到项目级、用户级和系统级配置文件，设置会被合并，项目级配置优先于用户级配置，用户级配置优先于系统级配置。（如果找到多个系统级配置文件，例如同时在 /etc/uv/uv.toml 和 $XDG_CONFIG_DIRS/uv/uv.toml，则只使用最先发现的那个，XDG 优先。）

例如，如果字符串、数字或布尔值同时存在于项目级和用户级配置表中，会使用项目级的值，用户级的值被忽略。如果数组同时存在于两个表中，数组会被拼接，项目级设置出现在合并后数组的前面。

通过环境变量提供的设置优先于持久配置，通过命令行提供的设置优先于两者。

uv 接受 --no-config 命令行参数，提供它会禁用任何持久配置的发现。

uv 也接受 --config-file 命令行参数，它接收一个 uv.toml 路径以用作配置文件。提供该参数时，这个文件会替代任何被发现的配置文件（例如用户级配置会被忽略）。

设置

可用设置的列表请参阅设置参考。

环境变量文件

uv run 可以从 dotenv 文件（例如 .env、.env.local、.env.development）加载环境变量，由 dotenvy crate 提供支持。

要从专用位置加载 .env 文件，请设置 UV_ENV_FILE 环境变量，或给 uv run 传入 --env-file 标志。

例如，从当前工作目录中的 .env 文件加载环境变量：

1
2
3

$ echo "MY_VAR='Hello, world!'" > .env
$ uv run --env-file .env -- python -c 'import os; print(os.getenv("MY_VAR"))'
Hello, world!

--env-file 标志可以多次提供，后提供的文件会覆盖先前文件中定义的值。要通过 UV_ENV_FILE 环境变量提供多个文件，请用空格分隔路径（例如 UV_ENV_FILE="/path/to/file1 /path/to/file2"）。

要禁用 dotenv 加载（例如覆盖 UV_ENV_FILE 或 --env-file 命令行参数），请把 UV_NO_ENV_FILE 环境变量设为 1，或给 uv run 传入 --no-env-file 标志。

如果同一个变量同时定义在环境和 .env 文件中，环境中的值优先。

配置 pip 接口

有一个专门的 [tool.uv.pip] 段落用于仅配置 uv pip 命令行接口。该段落中的设置不会应用于 uv pip 命名空间之外的 uv 命令。不过该段落中的许多设置在顶层命名空间中有对应项，除非被 uv.pip 段落中的值覆盖，否则这些对应项确实会应用于 uv pip 接口。

uv.pip 设置的设计目标是紧密贴合 pip 的接口，它们被单独声明是为了在保持兼容性的同时允许全局设置采用不同设计（例如 --no-build）。

举例来说，在 [tool.uv.pip] 下设置 index-url（如下面的 pyproject.toml），只会影响 uv pip 子命令（例如 uv pip install，而不会影响 uv sync、uv lock 或 uv run）：

1
2
3

# pyproject.toml
[tool.uv.pip]
index-url = "https://test.pypi.org/simple"