锁定环境

锁定的目的是获取一个依赖项（例如 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.py 和 setup.cfg 格式。 要锁定在 setup.py 中声明的依赖项

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

要从 stdin 锁定依赖项，请使用 -

$ echo "ruff" | uv pip compile -

要锁定启用可选依赖项（例如，“foo” extra）

$ uv pip compile pyproject.toml --extra foo

要锁定启用所有可选依赖项

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

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

要在当前项目目录的 pyproject.toml 中锁定依赖项组，例如组 foo

$ uv pip compile --group foo

重要

必须将 --group 标志添加到 pip-tools 的 pip compile 中，虽然他们正在考虑。 我们希望支持他们采用的任何语法和语义。

要指定应从中获取组的项目目录

$ uv pip compile --project some/path/ --group foo --group bar

或者，您可以为每个组指定 pyproject.toml 的路径

$ uv pip compile --group some/path/pyproject.toml:foo --group other/pyproject.toml:bar

注意

--group 标志不适用于其他指定的源。 例如，uv pip compile some/path/pyproject.toml --group foo 从 ./pyproject.toml 提取 foo，**而不是** some/path/pyproject.toml。

升级需求

使用输出文件时，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 标志。

同步环境

可以使用 uv pip install 直接从其定义文件或编译后的 requirements.txt 文件安装依赖项。 有关更多详细信息，请参阅有关 从文件安装软件包 的文档。

使用 uv pip install 安装时，除非已安装的软件包与锁定文件冲突，否则不会将其删除。 这意味着环境可能具有未在锁定文件中声明的依赖项，这对可重现性不利。 为了确保环境与锁定文件完全匹配，请改用 uv pip sync。

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

$ uv pip sync requirements.txt

要使用 PEP 751 pylock.toml 文件同步环境

$ uv pip sync pylock.toml

添加约束

约束文件是类似于 requirements.txt 的文件，仅控制已安装需求的 _version_。 但是，在约束文件中包含软件包将_不会_触发该软件包的安装。 约束可用于为当前项目不是依赖项的依赖项添加边界。

要定义约束，请为软件包定义一个边界

constraints.txt

pydantic<2.0

要使用约束文件

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

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

uv 还会从工作区根目录的 pyproject.toml 中读取 constraint-dependencies，并将它们附加到约束文件中指定的那些约束。

添加构建约束

与 constraints 类似，但专门用于构建时依赖项，包括构建运行时依赖项时所需的那些。

构建约束文件是类似于 requirements.txt 的文件，仅控制构建时需求的 _version_。 但是，在构建约束文件中包含软件包_不会_触发在构建时安装该软件包； 相反，约束仅适用于需要该软件包作为直接或传递构建时依赖项的情况。 构建约束可用于为当前项目未明确声明为构建时依赖项的依赖项添加边界。

例如，如果一个软件包按如下方式定义其构建依赖项

pyproject.toml

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

构建约束可用于确保工作空间中每个软件包都使用特定版本的 setuptools

build-constraints.txt

setuptools==75.0.0

uv 还会从工作区根目录的 pyproject.toml 中读取 build-constraint-dependencies，并将它们附加到构建约束文件中指定的那些约束。

覆盖依赖版本

覆盖文件是类似于 requirements.txt 的文件，它强制安装需求的特定版本，而不管任何组成软件包声明的需求如何，也无论这是否被认为是无效的解析。

约束是_附加的_，因为它们与组成软件包的需求结合在一起，而覆盖是_绝对的_，因为它们完全替换了组成软件包的需求。

覆盖最常用于从传递依赖项中删除上限。 例如，如果 a 需要 c>=1.0,<2.0，b 需要 c>=2.0，并且当前项目需要 a 和 b，则无法解析依赖项。

要定义覆盖，请为有问题的软件包定义新的需求

overrides.txt

c>=2.0

要使用覆盖文件

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

现在，解析可以成功。 但是，请注意，如果 a 是_正确的_，因为它不支持 c>=2.0，则在使用软件包时可能会遇到运行时错误。

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