配置文件
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
(如果没有这样的表,则 pyproject.toml
文件将被忽略,并且 uv 将继续在目录层次结构中搜索。)
uv 也会搜索 uv.toml
文件,这些文件遵循相同的结构,但省略了 [tool.uv]
前缀。例如
注意
uv.toml
文件优先于 pyproject.toml
文件,因此如果 uv.toml
和 pyproject.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 sync
、uv lock
或 uv run
)