锁定和同步
锁定是将项目的依赖项解析到一个锁定文件的过程。同步是将锁定文件中的一部分包安装到项目环境中的过程。
自动锁定和同步
在 uv 中，锁定和同步是自动的。 例如，当使用 uv run 时，在调用请求的命令之前，项目会被锁定和同步。 这确保项目环境始终是最新的。 同样，读取锁定文件的命令（例如 uv tree）将在运行之前自动更新它。
要禁用自动锁定，请使用 --locked 选项
如果锁定文件不是最新的，uv 将引发错误，而不是更新锁定文件。
要使用锁定文件而不检查它是否为最新，请使用 --frozen 选项
同样，要在不检查环境是否为最新的情况下运行命令，请使用 --no-sync 选项
检查锁定文件是否为最新
在考虑锁定文件是否为最新时，uv 将检查它是否与项目元数据匹配。 例如，如果您向 pyproject.toml 添加依赖项，锁定文件将被视为已过时。 同样，如果您更改依赖项的版本约束，以至于排除了锁定的版本，则锁定文件将被视为已过时。 但是，如果您更改版本约束，使得现有的锁定版本仍然包含在内，则锁定文件仍将被视为最新的。
您可以通过将 --check 标志传递给 uv lock 来检查锁定文件是否为最新
这等效于其他命令的 --locked 标志。
重要
当发布新版本的包时，uv 不会将锁定文件视为已过时 — 如果您想升级依赖项，则需要显式更新锁定文件。 有关详细信息，请参阅有关升级锁定的包版本的文档。
创建锁定文件
虽然锁定文件是自动创建的，但也可以使用 uv lock 显式创建或更新锁定文件
同步环境
虽然环境是自动同步的，但也可以使用 uv sync 显式同步环境
手动同步环境对于确保您的编辑器具有正确的依赖项版本特别有用。
可编辑安装
当环境同步时，uv 将项目（和其他工作区成员）安装为可编辑包，这样就不需要重新同步才能使更改反映在环境中。
要选择退出此行为，请使用 --no-editable 选项。
注意
如果项目未定义构建系统，则不会安装它。 有关详细信息，请参阅构建系统文档。
保留多余的包
默认情况下，同步是“精确的”，这意味着它将删除锁定文件中不存在的任何包。
要保留多余的包，请使用 --inexact 选项
同步可选依赖项
uv 从 [project.optional-dependencies] 表中读取可选依赖项。 这些通常被称为“extras”。
默认情况下，uv 不会同步 extras。 使用 --extra 选项来包含一个 extra。
要快速启用所有 extras，请使用 --all-extras 选项。
有关如何管理可选依赖项的详细信息，请参阅可选依赖项文档。
同步开发依赖项
uv 从 [dependency-groups] 表中读取开发依赖项（如 PEP 735 中所定义）。
dev 组是特殊情况，默认情况下会同步。 有关更改默认值的详细信息，请参阅默认组文档。
--no-dev 标志可用于排除 dev 组。
--only-dev 标志可用于安装 dev 组，而不包含项目及其依赖项。
可以使用 --all-groups、--no-default-groups、--group <name>、--only-group <name> 和 --no-group <name> 选项来包含或排除其他组。 --only-group 的语义与 --only-dev 相同，该项目将不会被包含在内。 但是，--only-group 也会排除默认组。
组排除始终优先于包含，因此给定命令
将不会安装 foo 组。
有关如何管理开发依赖项的详细信息，请参阅开发依赖项文档。
升级锁定的包版本
对于现有的 uv.lock 文件，当运行 uv sync 和 uv lock 时，uv 将优先使用先前锁定的包版本。 只有当项目的依赖项约束排除先前的锁定版本时，包版本才会更改。
要升级所有包
要将单个包升级到最新版本，同时保留所有其他包的锁定版本
要将单个包升级到特定版本
在所有情况下，升级都限于项目的依赖项约束。 例如，如果项目定义了包的上限，则升级不会超出该版本。
注意
uv 将类似的逻辑应用于 Git 依赖项。 例如，如果 Git 依赖项引用 main 分支，则除非使用 --upgrade 或 --upgrade-package 标志，否则 uv 将优先使用现有 uv.lock 文件中的锁定提交 SHA，而不是 main 分支上的最新提交。
这些标志也可以提供给 uv sync 或 uv run 以更新锁定文件和环境。
导出锁定文件
如果您需要将 uv 与其他工具或工作流程集成，则可以使用 uv export --format requirements-txt 将 uv.lock 导出为 requirements.txt 格式。 然后可以通过 uv pip install 或其他工具（如 pip）安装生成的 requirements.txt 文件。
一般来说，我们建议不要同时使用 uv.lock 和 requirements.txt 文件。 如果您发现自己导出 uv.lock 文件，请考虑提出一个问题来讨论您的用例。
部分安装
有时，以多个步骤执行安装会很有帮助，例如，在构建 Docker 镜像时实现最佳层缓存。 uv sync 有几个用于此目的的标志。
--no-install-project：不安装当前项目--no-install-workspace：不安装任何工作区成员，包括根项目--no-install-package <NO_INSTALL_PACKAGE>：不安装给定的包
当使用这些选项时，目标的**所有**依赖项仍然会被安装。例如， --no-install-project 将忽略_项目_，但不会忽略它的任何依赖项。
如果使用不当，这些标志可能会导致环境损坏，因为包可能缺少其依赖项。