3.4.7 构建分发包

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

3.4.7 构建分发包

要把项目分发给他人（例如上传到 PyPI 之类的索引），你需要把它构建成可分发的格式。

Python 项目通常同时以源码分发（sdist）和二进制分发（wheel）形式分发。前者通常是包含项目源代码及一些附加元数据的 .tar.gz 或 .zip 文件，后者是包含可直接安装的预构建产物的 .whl 文件。

重要

使用 uv build 时，uv 充当构建前端，只负责确定使用的 Python 版本并调用构建后端。构建的细节（例如包含的文件和分发包文件名）由 [build-system] 中定义的构建后端决定。构建配置信息可以在相应工具的文档中找到。

使用 uv build

uv build 可以用来为项目构建源码分发和二进制分发。默认情况下，uv build 会构建当前目录中的项目，并把构建产物放入 dist/ 子目录：

1
2
3
4

$ uv build
$ ls dist/
example-0.1.0-py3-none-any.whl
example-0.1.0.tar.gz

你可以通过给 uv build 提供路径来构建其他目录中的项目，例如 uv build path/to/project。

uv build 会先构建源码分发，再从该源码分发构建二进制分发（wheel）。

你可以用 uv build --sdist 把 uv build 限制为只构建源码分发，用 uv build --wheel 只构建二进制分发，或用 uv build --sdist --wheel 从源码构建两种分发。

构建约束

uv build 接受 --build-constraint，用于在构建过程中约束任何构建要求的版本。与 --require-hashes 搭配使用时，uv 会强制用于构建项目的要求匹配特定且已知的哈希，以保证可复现性。

例如，给定如下 constraints.txt：

1

setuptools==68.2.2 --hash=sha256:b454a35605876da60632df1a60f736524eb73cc47bbc9f3f1ef1b644de74fd2a

运行下面的命令会用指定版本的 setuptools 构建项目，并校验下载的 setuptools 分发与指定的哈希一致：

1

$ uv build --build-constraint constraints.txt --require-hashes

项目构建依赖哈希

项目也可以在 build-constraint-dependencies 中指定构建约束。要校验下载的构建依赖，请以表的形式提供它的 requirement 和 hashes：

1
2
3
4
5

[tool.uv]
build-constraint-dependencies = [
    { requirement = "setuptools==68.2.2", hashes = ["sha256:b454a35605876da60632df1a60f736524eb73cc47bbc9f3f1ef1b644de74fd2a"] },
    "wheel<1",
]

不带哈希的条目可以写成字符串，如上面的 wheel<1 所示。uv 在项目解析或安装期间下载已固定的构建依赖时会校验提供的哈希，包括 uv run --with 环境中的构建。这些哈希适用于构建依赖。安装到项目环境中的包则用它们各自的锁文件哈希进行校验。

防止发布到 PyPI

如果你有不想发布的内部包，可以把它们标记为私有：

1
2

[project]
classifiers = ["Private :: Do Not Upload"]

该设置会让 PyPI 拒绝发布你上传的包。它不影响其他仓库上的安全或隐私设置。

我们还建议只生成按项目划分的 PyPI API 令牌：如果没有与该包匹配的 PyPI 令牌，它就不会被误发布。