跳到内容

配置文件

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

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

注意

对于在用户级别操作的 tool 命令,将忽略本地配置文件。相反,uv 将专门从用户级别配置(例如,~/.config/uv/uv.toml)和系统级别配置(例如,/etc/uv/uv.toml)读取。

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

如果找到 pyproject.toml 文件,uv 将从 [tool.uv] 表中读取配置。例如,要设置持久索引 URL,请将以下内容添加到 pyproject.toml

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

(如果没有这样的表,则 pyproject.toml 文件将被忽略,并且 uv 将继续在目录层次结构中搜索。)

uv 也会搜索 uv.toml 文件,这些文件遵循相同的结构,但省略了 [tool.uv] 前缀。例如

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

注意

uv.toml 文件优先于 pyproject.toml 文件,因此如果 uv.tomlpyproject.toml 文件都存在于一个目录中,配置将从 uv.toml 读取,并且随附的 pyproject.toml 中的 [tool.uv] 部分将被忽略。

uv 还将在 macOS 和 Linux 上的 ~/.config/uv/uv.toml (或 $XDG_CONFIG_HOME/uv/uv.toml) 以及 Windows 上的 %APPDATA%\uv\uv.toml 中发现用户级别的配置;在 macOS 和 Linux 上的 /etc/uv/uv.toml (或 $XDG_CONFIG_DIRS/uv/uv.toml) 以及 Windows 上的 %SYSTEMDRIVE%\ProgramData\uv\uv.toml 中发现系统级别的配置。

用户级别和系统级别的配置必须使用 uv.toml 格式,而不是 pyproject.toml 格式,因为 pyproject.toml 旨在定义 Python *项目*。

如果找到项目级别、用户级别和系统级别的配置文件,这些设置将被合并,项目级别的配置优先于用户级别的配置,而用户级别的配置优先于系统级别的配置。(如果找到多个系统级别的配置文件,例如,在 /etc/uv/uv.toml$XDG_CONFIG_DIRS/uv/uv.toml 中,则只会使用第一个发现的文件,XDG 优先。)

例如,如果字符串、数字或布尔值同时存在于项目级别和用户级别的配置表中,则将使用项目级别的值,而用户级别的值将被忽略。如果一个数组同时存在于两个表中,则这些数组将被连接起来,项目级别的设置会出现在合并数组的更早位置。

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

uv 接受 --no-config 命令行参数,提供此参数时,将禁用任何持久性配置的发现。

uv 还接受 --config-file 命令行参数,该参数接受 uv.toml 的路径作为配置文件。提供此参数时,将使用此文件代替*任何*已发现的配置文件(例如,用户级别的配置将被忽略)。

设置

有关可用设置的枚举,请参阅设置参考

.env

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

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

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

$ 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,或将 --no-env-file 标志传递给 uv run

如果在环境和 .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 syncuv lockuv run

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