锁定与同步
锁定（Locking）是将项目的依赖项解析为锁文件（lockfile）的过程。同步（Syncing）是将锁文件中的一部分包安装到项目环境中的过程。
自动锁定与同步
锁定和同步在 uv 中是自动进行的。例如，当使用 uv run 时，项目会在执行所请求的命令之前先进行锁定和同步。这确保了项目环境始终保持最新。同样，读取锁文件的命令（如 uv tree）也会在运行前自动更新锁文件。
要禁用自动锁定，请使用 --locked 选项：
如果锁文件不是最新的，uv 将报错而不是更新锁文件。
要使用锁文件但不检查其是否是最新的，请使用 --frozen 选项：
同样，要在不检查环境是否是最新的情况下运行命令，请使用 --no-sync 选项：
检查锁文件
在判断锁文件是否是最新时，uv 会检查其是否与项目元数据匹配。例如，如果您在 pyproject.toml 中添加了一个依赖项，锁文件将被视为过期。同样，如果您更改了某个依赖项的版本约束，导致已锁定的版本被排除在外，锁文件也将被视为过期。但是，如果您更改版本约束后，已锁定的版本仍然被包含在内，锁文件仍将被视为最新。
您可以通过向 uv lock 传递 --check 标志来检查锁文件是否是最新的：
这相当于其他命令中的 --locked 标志。
Important
当新版本的包发布时，uv 不会将锁文件视为过期——如果您想升级依赖项，需要显式更新锁文件。详情请参阅升级锁定的包版本文档。
创建锁文件
虽然锁文件是自动创建的，但也可以使用 uv lock 显式创建或更新锁文件：
同步环境
虽然环境是自动同步的，但也可以使用 uv sync 显式同步环境：
手动同步环境对于确保您的编辑器拥有正确版本的依赖项特别有用。
可编辑安装
当环境被同步时，uv 会将项目（以及其他工作空间成员）安装为可编辑（editable）包，这样对代码的更改无需重新同步即可反映在环境中。
要退出此行为，请使用 --no-editable 选项。
Note
如果项目未定义构建系统，则不会被安装。详情请参阅构建系统文档。
处理多余包
uv sync 默认执行"精确"（exact）同步，这意味着它会移除锁文件中不存在的任何包。
要保留多余包，请使用 --inexact 标志：
相比之下，uv run 默认使用"非精确"（inexact）同步，确保所有必需的包都已安装，但不会移除多余包。要在 uv run 中启用精确同步，请使用 --exact 标志：
同步可选依赖
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 会优先使用之前锁定的包版本。只有当项目的依赖约束排除了之前锁定的版本时，包版本才会发生变化。
要升级所有包：
要将单个包升级到最新版本，同时保留所有其他包的锁定版本：
要将单个包升级到特定版本：
在所有情况下，升级都受限于项目的依赖约束。例如，如果项目为某个包定义了上限版本，那么升级将不会超过该版本。
Note
uv 对 Git 依赖项也应用类似的逻辑。例如，如果某个 Git 依赖项引用了 main 分支，uv 会优先使用已有 uv.lock 文件中锁定的提交 SHA，而不是 main 分支上的最新提交，除非使用了 --upgrade 或 --upgrade-package 标志。
这些标志也可以提供给 uv sync 或 uv run，以同时更新锁文件和环境。
导出锁文件
如果您需要将 uv 与其他工具或工作流集成，可以将 uv.lock 导出为不同的格式，包括 requirements.txt、pylock.toml（PEP 751）和 CycloneDX SBOM。
$ uv export --format requirements.txt
$ uv export --format pylock.toml
$ uv export --format cyclonedx1.5
有关所有导出格式及其用例的全面文档，请参阅导出指南。
部分安装
有时分步执行安装会很有帮助，例如在构建 Docker 镜像时为了优化层缓存。uv sync 提供了几个用于此目的的标志。
--no-install-project：不安装当前项目--no-install-workspace：不安装任何工作空间成员，包括根项目--no-install-package <NO_INSTALL_PACKAGE>：不安装指定的包
使用这些选项时，目标的所有依赖项仍然会被安装。例如，--no-install-project 会省略项目本身，但不会省略其任何依赖项。
如果使用不当，这些标志可能会导致环境损坏，因为某个包可能会缺少其依赖项。
恶意软件检查
Important
同步时的恶意软件检查处于预览阶段，在稳定之前可能会发生变化。
在同步过程中，uv 可以通过对照 OSV 对锁文件进行轻量级扫描来检查已知恶意软件。OSV 引用了 OpenSSF 的恶意包数据库中的 MAL 通告。
如果锁定的依赖项匹配到恶意软件通告，同步将被终止。
要启用恶意软件检查，请在环境中设置 UV_MALWARE_CHECK=1。