锁定与同步
锁定是指将项目的依赖项解析到锁定文件中的过程。同步是指从锁定文件中将部分软件包安装到项目环境中的过程。
自动锁定与同步
在 uv 中，锁定与同步是自动进行的。例如，使用 uv run 时，在调用请求的命令之前，会先对项目进行锁定和同步。这确保了项目环境始终是最新的。同样，像 uv tree 这类读取锁定文件的命令，在运行之前也会自动更新锁定文件。
要禁用自动锁定，可以使用 --locked 选项：
如果锁定文件不是最新的，uv 将引发错误，而不是更新锁定文件。
要使用锁定文件而不检查其是否为最新，可以使用 --frozen 选项：
同样，要运行命令而不检查环境是否为最新，可以使用 --no-sync 选项：
检查锁文件是否为最新版本
在判断锁文件是否为最新版本时，uv 会检查它是否与项目元数据匹配。例如，如果你在 pyproject.toml 中添加了一个依赖项，锁文件将被视为过时。同样，如果你更改了某个依赖项的版本约束，导致锁定的版本被排除在外，锁文件也将被视为过时。但是，如果你更改版本约束后，现有的锁定版本仍包含在内，锁文件仍将被视为最新版本。
你可以通过在 uv lock 命令中传递 --check 标志来检查锁文件是否为最新版本：
这与其他命令中的 --locked 标志等效。
Important
当有新版本的软件包发布时，uv 不会将锁文件视为过时——如果你想升级依赖项，需要显式更新锁文件。有关详细信息，请参阅 升级锁定的软件包版本 的文档。
创建锁文件
虽然锁文件会 自动创建，但也可以使用 uv lock 显式创建或更新锁文件：
同步环境
虽然环境会 自动同步，但也可以使用 uv sync 显式同步：
手动同步环境对于确保你的编辑器拥有正确版本的依赖项特别有用。
可编辑安装
同步环境时，uv 会将项目（及其他工作区成员）安装为可编辑包，这样一来，环境中就能即时反映出变更，无需重新同步。
若要取消此行为，请使用 --no-editable 选项。
注意
如果项目未定义构建系统，则不会安装。 有关详细信息，请参阅构建系统文档。
保留无关包
默认情况下，同步是 “精确” 的，这意味着它将删除锁文件中不存在的任何包。
若要保留无关包，请使用 --inexact 选项：
同步可选依赖项
uv 从 [project.optional-dependencies] 表中读取可选依赖项。这些通常被称为 “额外项”。
默认情况下，uv 不会同步额外项。使用 --extra 选项来包含一个额外项。
若要快速启用所有额外项，请使用 --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 分支，uv 会优先使用现有 uv.lock 文件中锁定的提交 SHA，而不是 main 分支上的最新提交，除非使用了 --upgrade 或 --upgrade-package 标志。
这些标志也可以提供给 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 将忽略 项目，但不会忽略其任何依赖项。
如果使用不当，这些标志可能会导致环境损坏，因为某个包可能缺少其依赖项。