uv export：将 uv.lock 导出为 requirements.txt、pylock.toml 与 CycloneDX SBOM 的实践指南

本文基于 uv 仓库中 导出锁文件 官方文档展开，系统讲解 uv export 命令支持的三种输出格式（requirements.txt、pylock.toml、cyclonedx1.5）、关键命令行参数及其行为细节，并结合 导出实现源码 说明格式推断、锁文件前置锁定、冲突检测等底层机制。读完本文，你可以熟练地把 uv 项目的依赖锁文件转换为 pip 兼容清单、PEP 751 标准锁文件或符合 CycloneDX v1.5 规范的 SBOM，用于 CI 构建、安全审计与供应链合规场景。

导出格式总览

uv 可以将项目的 uv.lock 锁文件导出为其他工具与工作流可消费的格式。目前共支持三种格式：

• requirements.txt：传统的 pip 兼容 requirements 文件格式，是绝大多数 Python 生态工具都能消费的形式；
• pylock.toml：PEP 751 定义的标准化 Python 锁文件格式（TOML 编码）；
• cyclonedx1.5：工业标准的软件物料清单（SBOM）格式，机器可读，被安全扫描工具、漏洞数据库与 SCA 平台广泛支持。

格式通过 --format 标志显式指定：

$ uv export --format requirements.txt
$ uv export --format pylock.toml
$ uv export --format cyclonedx1.5

格式取值在 ExportFormat 枚举 中定义，其中 requirements.txt 是 #[default] 默认值，且各格式都提供了连字符别名（如 requirements-txt、pylock-toml）以方便 TOML/JSON 配置场景。

提示：uv export 默认将结果打印到 stdout；如需写入文件，为任意格式追加 --output-file：

$ uv export --format requirements.txt --output-file requirements.txt
$ uv export --format pylock.toml --output-file pylock.toml
$ uv export --format cyclonedx1.5 --output-file sbom.json

requirements.txt 格式

requirements.txt 是对 Python 依赖支持最广泛的格式，导出结果可直接交给 uv pip install 或 pip 等工具安装。

基本用法

$ uv export --format requirements.txt

官方文档在此处给出一条明确的工程建议：通常不建议同时维护 uv.lock 和 requirements.txt 两份文件。uv.lock 的表达力更强，包含 requirements.txt 无法表达的特性（如环境标记、per-package 索引固定等）。如果你发现必须频繁导出 requirements.txt，官方建议向上游提 issue 讨论具体使用场景，以便格式本身演进。

输出内容与控制参数

从 导出命令实现 看，requirements.txt 的生成过程包含几个可选"前言"与后处理环节：

参数	作用
（默认开启）	在文件头部写入自动生成的注释头，标明生成该文件所用的 uv 命令行
--no-header	去掉注释头（ExportArgs 定义）
--no-annotate	去掉每行依赖来源包名的注释标注
--emit-index-url	在输出中写入 --index-url 与 --extra-index-url 条目
--emit-find-links	在输出中写入 --find-links 条目
--hashes	为所有依赖附加哈希（隐藏开关，与 --no-hashes 互斥）

两个值得注意的实现细节：

1. per-package 索引固定的降级处理。当项目为个别包指定了显式索引（explicit index）时，requirements.txt 格式本身不支持按包固定索引，源码会将其全局展开为 --extra-index-url 并打印警告：`requirements.txt` does not support per-package index pinning; explicit indexes were emitted globally via `--extra-index-url`.（export.rs）。
2. 输出文件名为 pyproject.toml 时直接报错。实现中显式拦截这种情况，提示支持的格式列表（export.rs），防止误覆盖项目元数据文件。

格式推断

不传 --format 时，uv 会尝试从 --output-file 推断格式（export.rs）：扩展名为 .txt 视为 requirements.txt；文件名符合 pylock.toml 或 pylock.<name>.toml 约定（<name> 非空且不含点）则视为 pylock.toml；否则回退到默认的 requirements.txt。这与 CLI 参考 中 --format 的描述一致："uv will infer the output format from the file extension of the output file, if provided. Otherwise, defaults to requirements.txt"。

pylock.toml 格式（PEP 751）

PEP 751 定义了基于 TOML 的 Python 依赖锁文件格式，目标是让锁文件在不同工具间互换。uv 可以将项目的依赖锁文件导出为该格式：

$ uv export --format pylock.toml

从源码看，pylock.toml 的导出同样经过与 requirements.txt 相同的 extras/groups 过滤、prune 等处理（调用 PylockToml::from_lock，见 export.rs），并支持 --no-annotate 与注释头控制。

实现中还有一处硬性校验：导出为 PEP 751 格式时，若 --output-file 的文件名不符合 pylock.toml 或 pylock.<name>.toml（<name> 非空且不含点）的规范命名，会直接报错退出（export.rs）。这保证了导出产物满足 PEP 751 的文件命名约定，可被其他遵循该 PEP 的工具识别。

CycloneDX SBOM 格式

uv 可以将项目的依赖锁文件导出为 CycloneDX 格式的 SBOM。SBOM 提供应用内所有软件组件的完整清单，对安全审计、合规检查和供应链透明度尤为重要。

注意：CycloneDX 导出功能目前处于 preview 状态，未来版本可能随时变化。

基本用法

$ uv export --format cyclonedx1.5

生成结果为 JSON 编码的 CycloneDX v1.5 文档，包含项目本身及其全部依赖（由 cyclonedx_json::from_lock 生成，见 export.rs）。

SBOM 结构与自定义属性

生成的 SBOM 遵循 CycloneDX 规范，且 uv 在组件上额外附加了两个自定义属性（custom properties）：

• uv:package:marker：环境标记，例如 python_version >= "3.8"；
• uv:workspace:path：workspace 成员的相对路径。

这两个属性弥补了标准 CycloneDX 结构无法表达"依赖仅在特定环境下生效"和"依赖来自本地 workspace 成员"这两类 uv 特有信息的不足，消费端可以据此还原更精确的依赖语义。

另一个实现层面的细节：对非 CycloneDX 格式，导出前会执行依赖冲突检测（detect_conflicts）；而 SBOM 的语义本就是"如实记录全部组件（包括冲突组件）"，因此 CycloneDX 导出会跳过冲突检测（export.rs 中的注释明确了这一设计意图）。

通用参数：工作区、extras 与依赖组

除格式相关参数外，uv export 还有一组跨格式生效的选择性参数（定义于 ExportArgs）：

• --all-packages：导出整个 workspace，所有成员的依赖都会包含在导出结果中；--extra、--group 等选项会应用到全部成员。与 --package 互斥。
• --package：仅导出 workspace 中指定包的依赖；若指定了不存在的成员会报错退出。
• --prune PACKAGE：从依赖树中剪掉指定包，剪枝后不再被任何路径依赖的依赖也会一并排除。
• --extra / --all-extras / --no-extra：控制可选依赖（extras）的包含范围。
• 依赖组（dependency groups）：通过扁平化的 ProjectDependencyGroupsArgs 参数控制 dev 等依赖组的包含。
• --no-emit-project / --only-emit-project：默认导出包含当前项目自身及其全部依赖；--no-emit-project 排除项目本体但保留其依赖，--only-emit-project 则相反（CLI 参考）。
• --no-emit-workspace / --only-emit-workspace：对 workspace 成员做同样的双向过滤。
• editable 系列（--no-editable、--no-editable-package，以及环境变量 UV_NO_EDITABLE）：控制项目与 workspace 成员以可编辑还是非可编辑形式写入导出文件。

从 导出流程源码 可以确认这些参数的生效链路：命令先通过 ExportTarget 枚举区分两类导出目标——PEP 723 脚本（--script 指向带内联元数据的单文件脚本）与 pyproject.toml 项目（支持按 --package 定位 workspace 内指定项目）；随后合并默认依赖组与默认 extras，再进入锁定阶段。

锁定阶段的行为也值得了解（export.rs）：

• 默认以 LockMode::Write 运行，即先（重新）锁定、再导出，保证导出结果与最新 uv.lock 一致；
• 对 PEP 723 脚本，若本地不存在锁文件则退化为 LockMode::DryRun，避免仅为导出而创建锁文件；
• --frozen 会跳过解释器发现与网络操作，直接基于现有锁文件导出。

适用场景小结

场景	推荐格式	说明
交给 pip / uv pip install 安装	requirements.txt	兼容性最广；注意 uv.lock 表达力更强，官方不鼓励双文件长期并存
需要可互换的标准锁文件	pylock.toml	遵循 PEP 751；输出文件名必须符合 pylock.toml / pylock.<name>.toml 约定
安全审计、合规、SCA 扫描	cyclonedx1.5	JSON SBOM，含 uv:package:marker、uv:workspace:path 自定义属性；当前处于 preview 阶段

下一步

• 了解锁文件的布局与生成机制：项目布局 与 锁定与同步；
• 了解 preview 功能的启用方式：Preview 文档；
• 导出之后，继续阅读如何构建并发布项目到包索引。