锁定和同步
锁定是将项目依赖项解析为锁文件的过程。同步是将锁文件中的部分包安装到项目环境中的过程。
自动锁定与同步
在 uv 中，锁定和同步是自动进行的。例如，当使用 uv run 时，会在调用请求的命令之前对项目进行锁定和同步。这确保了项目环境始终是最新的。同样，读取锁文件的命令（如 uv tree）也会在运行前自动更新锁文件。
要禁用自动锁定，请使用 --locked 选项
如果锁文件不是最新的，uv 将报错，而不会更新锁文件。
若要在不检查锁文件是否为最新的情况下使用它，请使用 --frozen 选项
同样，若要在不检查环境是否为最新的情况下运行命令，请使用 --no-sync 选项
检查锁文件
当判断锁文件是否为最新时，uv 会检查它是否与项目元数据匹配。例如，如果您向 pyproject.toml 添加了依赖项，锁文件将被视为过期。类似地，如果您更改了依赖项的版本约束，使得已锁定的版本被排除在外，锁文件也会被视为过期。但是，如果您更改了版本约束，而现有的已锁定版本仍然满足要求，那么锁文件仍将被视为最新。
您可以通过向 uv lock 传递 --check 标志来检查锁文件是否为最新
这等同于其他命令中的 --locked 标志。
重要
当包发布新版本时，uv 不会将锁文件视为过期 —— 如果您想升级依赖项，则需要显式更新锁文件。有关详细信息，请参阅关于升级已锁定包版本的文档。
创建锁文件
虽然锁文件是自动创建的，但也可以使用 uv lock 显式创建或更新它
同步环境
虽然环境是自动同步的，但也可以使用 uv sync 显式同步它
手动同步环境对于确保您的编辑器拥有正确的依赖版本特别有用。
可编辑安装
当环境同步时，uv 会将项目（以及其他工作区成员）作为可编辑包安装，这样对代码的更改无需重新同步即可反映在环境中。
要选择不使用此行为，请使用 --no-editable 选项。
注意
如果项目没有定义构建系统，它将不会被安装。有关详细信息，请参阅构建系统文档。
处理额外包
uv sync 默认执行“精确”同步，这意味着它将删除任何不存在于锁文件中的包。
要保留额外包，请使用 --inexact 标志
相比之下，uv run 默认使用“非精确”同步，确保安装所有必需的包，但不删除额外包。若要在 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 会优先使用之前锁定的包版本。只有当项目的依赖约束排除了先前锁定的版本时，包版本才会改变。
要升级所有包
要将单个包升级到最新版本，同时保留所有其他包的锁定版本
要将单个包升级到特定版本
在所有情况下，升级都受限于项目的依赖约束。例如，如果项目为某个包定义了上限，则升级不会超过该版本。
注意
uv 对 Git 依赖项应用了类似的逻辑。例如，如果 Git 依赖项引用了 main 分支，除非使用了 --upgrade 或 --upgrade-package 标志，否则 uv 会优先使用现有 uv.lock 文件中锁定的提交 SHA，而不是 main 分支上的最新提交。
这些标志也可以传递给 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 将省略项目本身，但不会省略其任何依赖项。
如果使用不当，这些标志可能导致环境损坏，因为包可能会丢失其依赖项。