3.4.5 锁定与同步

原文链接: https://docs.astral.sh/uv/concepts/projects/sync/

3.4.5 锁定与同步

锁定是指把项目依赖解析为锁文件的过程。同步是指把锁文件中的一部分包安装到项目环境的过程。

自动锁定与同步

在 uv 中，锁定和同步是自动的。例如使用 uv run 时，会在调用所请求的命令之前先锁定并同步项目。这确保项目环境始终是最新的。同样，读取锁文件的命令（例如 uv tree）也会在运行前自动更新锁文件。

要禁用自动锁定，请使用 --locked 选项：

1

$ uv run --locked ...

如果锁文件不是最新的，uv 会报错而不是更新锁文件。

要使用锁文件而不检查它是否最新，请使用 --frozen 选项：

1

$ uv run --frozen ...

同样，要在不检查环境是否最新的情况下运行命令，请使用 --no-sync 选项：

1

$ uv run --no-sync ...

检查锁文件

判断锁文件是否最新时，uv 会检查它是否与项目元数据一致。例如，如果你向 pyproject.toml 添加依赖，锁文件就会被视为过期。同样，如果你修改某个依赖的版本约束，导致已锁定的版本被排除，锁文件也会被视为过期。不过，如果你修改版本约束后既有的锁定版本仍在范围内，锁文件仍被视为最新。

你可以通过给 uv lock 传入 --check 标志来检查锁文件是否最新：

1

$ uv lock --check

这等价于其他命令的 --locked 标志。

重要

当包发布新版本时，uv 不会认为锁文件过期 —— 如果你想升级依赖，需要显式更新锁文件。细节请参阅升级已锁定的包版本文档。

创建锁文件

锁文件会自动创建，也可以用 uv lock 显式创建或更新：

1

$ uv lock

同步环境

环境会自动同步，也可以用 uv sync 显式同步：

1

$ uv sync

手动同步环境对确保编辑器使用正确的依赖版本特别有用。

可编辑安装

同步环境时，uv 会把项目（以及其他工作区成员）安装为可编辑包，这样修改无需重新同步即可反映到环境中。

要退出该行为，请使用 --no-editable 选项。

注意

如果项目未定义构建系统，它不会被安装。细节请参阅构建系统文档。

多余包的处理

uv sync 默认执行“精确”同步，也就是说，它会移除锁文件中不存在的任何包。

要保留多余的包，请使用 --inexact 标志：

1

$ uv sync --inexact

相比之下，uv run 默认使用“非精确”同步，确保所有必需的包都已安装，但不会移除多余的包。要让 uv run 执行精确同步，请使用 --exact 标志：

1

$ uv run --exact ...

同步可选依赖

uv 从 [project.optional-dependencies] 表读取可选依赖。它们通常被称为 “extras”。

uv 默认不同步 extras。请使用 --extra 选项包含某个 extra。

1

$ uv sync --extra foo

要快速启用所有 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 还会排除默认组。

组的排除总是优先于包含，因此对于如下命令：

$ uv sync --no-group foo --group foo

foo 组不会被安装。

管理开发依赖的细节请参阅开发依赖文档。

升级已锁定的包版本

在已有 uv.lock 文件的情况下，运行 uv sync 和 uv lock 时 uv 会优先使用此前锁定的包版本。只有当项目的依赖约束排除了此前锁定的版本时，包版本才会变化。

要升级所有包：

1

$ uv lock --upgrade

要把单个包升级到最新版本，同时保留其他所有包的锁定版本：

1

$ uv lock --upgrade-package <package>

要把单个包升级到指定版本：

1

$ uv lock --upgrade-package <package>==<version>

在所有情况下，升级都受项目依赖约束的限制。例如，如果项目为某个包定义了上界，升级就不会超过该版本。

注意

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。

1
2
3

$ 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 会省略项目，但不会省略它的任何依赖。

如果使用不当，这些标志可能导致环境损坏，因为某个包可能缺少它的依赖。

恶意软件检查

重要

同步时的恶意软件检查处于预览阶段，在稳定之前可能发生变化。

同步时，uv 可以通过把锁文件与 OSV 比对，对已知恶意软件进行轻量扫描。OSV 引用了 OpenSSF 恶意包数据库中的 MAL 公告。

如果某个已锁定的依赖匹配到恶意软件公告，同步会被终止。

要启用恶意软件检查，请在 uv 设置中设置 audit.malware-check = true，或在环境中设置 UV_MALWARE_CHECK=1。

要使用其他漏洞服务，请在 uv 设置中设置 audit.malware-check-url，或在环境中设置 UV_MALWARE_CHECK_URL。