跳转至

锁定环境

锁定是指将某个依赖(例如,ruff)的确切版本写入文件。处理多个依赖时,锁定确切版本非常有用,因为它可以确保环境的可重现性。如果不进行锁定,依赖的版本可能会随着时间变化、使用不同的工具或跨平台时发生变化。

锁定依赖

uv 允许将依赖锁定为 requirements.txt 格式。建议使用标准的 pyproject.toml 文件来定义依赖,但也支持其他依赖格式。有关如何定义依赖的更多信息,请参阅声明依赖文档。

要锁定在 pyproject.toml 中声明的依赖:

$ uv pip compile pyproject.toml -o requirements.txt

请注意,默认情况下,uv pip compile 的输出只会显示,并且需要 --output-file-o 参数来将其写入文件。

要锁定在 requirements.in 中声明的依赖:

$ uv pip compile requirements.in -o requirements.txt

要锁定在多个文件中声明的依赖:

$ uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt

uv 还支持旧版的 setup.pysetup.cfg 格式。要锁定在 setup.py 中声明的依赖:

$ uv pip compile setup.py -o requirements.txt

要从标准输入锁定依赖,使用 -

$ echo "ruff" | uv pip compile -

要在启用可选依赖的情况下进行锁定,例如启用 "foo" extra:

$ uv pip compile pyproject.toml --extra foo

要在启用所有可选依赖的情况下进行锁定:

$ uv pip compile pyproject.toml --all-extras

请注意,requirements.in 格式不支持 extras。

升级依赖

使用输出文件时,uv 会考虑现有输出文件中固定的版本。如果某个依赖被固定,它将在后续的编译运行中不会被升级。例如:

$ echo "ruff==0.3.0" > requirements.txt
$ echo "ruff" | uv pip compile - -o requirements.txt
# This file was autogenerated by uv via the following command:
#    uv pip compile - -o requirements.txt
ruff==0.3.0

要升级依赖,可以使用 --upgrade-package 标志:

$ uv pip compile - -o requirements.txt --upgrade-package ruff

要升级所有依赖,可以使用 --upgrade 标志。

同步环境

依赖可以直接从它们的定义文件或已编译的 requirements.txt 文件中安装,使用 uv pip install 命令。有关更多细节,请参阅从文件安装包文档。

使用 uv pip install 安装时,已安装的包不会被删除,除非它们与锁定文件冲突。这意味着环境中可能存在一些未在锁定文件中声明的依赖,这不利于环境的可重现性。为了确保环境与锁定文件完全一致,应该使用 uv pip sync

要使用 requirements.txt 文件同步环境:

$ uv pip sync requirements.txt

要使用 pyproject.toml 文件同步环境:

$ uv pip sync pyproject.toml

添加约束

约束文件类似于 requirements.txt 文件,只是它们控制的是安装的依赖项的版本。将包包含在约束文件中不会触发该包的安装。约束可以用于为当前项目没有直接依赖的依赖项添加版本范围。

要定义约束,可以为包定义一个版本范围:

constraints.txt
pydantic<2.0

要使用约束文件:

$ uv pip compile requirements.in --constraint constraints.txt

请注意,每个文件中可以定义多个约束,并且可以使用多个约束文件。

覆盖依赖版本

覆盖文件类似于 requirements.txt 文件,它们强制安装特定版本的依赖项,无论该依赖项是否被任何其他包声明,且无论这种安装是否会被认为是无效的解析。

约束是附加的,即它们与构成包的依赖要求结合使用,而覆盖是绝对的,即它们完全替代构成包的依赖要求。

覆盖通常用于移除传递性依赖的上限。例如,如果 a 需要 c>=1.0,<2.0b 需要 c>=2.0,而当前项目同时依赖 ab,则依赖无法解析。

要定义覆盖,可以为问题包定义新的依赖要求:

overrides.txt
c>=2.0

要使用覆盖文件:

$ uv pip compile requirements.in --override overrides.txt

现在,依赖解析可以成功完成。然而,请注意,如果 a 的要求是正确的,它不支持 c>=2.0,则在使用这些包时可能会遇到运行时错误。

请注意,每个文件中可以定义多个覆盖,并且可以使用多个覆盖文件。