构建并发布包

uv 支持通过 uv build 将 Python 项目构建为源码发行包和二进制分发包，并通过 uv publish 将其上传到仓库。

准备你的项目

在尝试发布项目之前，请确保它已准备好进行分发打包。

如果你的项目在 pyproject.toml 中没有包含 [build-system] 定义，uv 在项目内的 uv sync 操作期间不会对其进行构建，但在 uv build 时会回退到旧版的 setuptools 构建系统。

我们强烈建议配置一个构建系统。请在项目配置文档中阅读有关构建系统的更多信息。

构建你的包

使用 uv build 构建你的包

$ uv build

默认情况下，uv build 会构建当前目录中的项目，并将构建出的产物放置在 dist/ 子目录中。

此外，uv build <SRC> 会在指定目录中构建包，而 uv build --package <PACKAGE> 会构建当前工作空间中的指定包。

信息

默认情况下，uv build 在从 pyproject.toml 的 build-system.requires 部分解析构建依赖项时会遵循 tool.uv.sources。发布包时，我们建议运行 uv build --no-sources，以确保在禁用 tool.uv.sources（例如使用其他构建工具如 pypa/build 时）的情况下包也能正确构建。

更新你的版本号

uv version 命令提供了在发布前更新包版本号的便捷方式。查看项目文档以了解如何读取包的版本号。

要更新为确切的版本号，请将其作为位置参数提供

$ uv version 1.0.0
hello-world 0.7.0 => 1.0.0

要预览更改而不更新 pyproject.toml，请使用 --dry-run 标志

$ uv version 2.0.0 --dry-run
hello-world 1.0.0 => 2.0.0
$ uv version
hello-world 1.0.0

要按照语义化规则增加包版本号，请使用 --bump 选项

$ uv version --bump minor
hello-world 1.2.3 => 1.3.0

--bump 选项支持以下常见的版本组件：major（主版本）、minor（次版本）、patch（补丁）、stable（稳定版）、alpha、beta、rc、post 和 dev。当多次提供参数时，组件将按从最大 (major) 到最小 (dev) 的顺序应用。

你可以选择提供数值，使用 --bump <component>=<value> 来明确设置生成的组件值

$ uv version --bump patch --bump dev=66463664
hello-world 0.0.1 => 0.0.2.dev66463664

要从稳定版切换到预发布版本，除了预发布组件外，还要增加 major、minor 或 patch 组件之一

$ uv version --bump patch --bump beta
hello-world 1.3.0 => 1.3.1b1
$ uv version --bump major --bump alpha
hello-world 1.3.0 => 2.0.0a1

从一个预发布版本移动到另一个新的预发布版本时，只需增加相关的预发布组件即可

$ uv version --bump beta
hello-world 1.3.0b1 => 1.3.0b2

从预发布版本切换到稳定版本时，可以使用 stable 选项清除预发布组件

$ uv version --bump stable
hello-world 1.3.1b2 => 1.3.1

信息

默认情况下，当 uv version 修改项目时，它会执行锁定 (lock) 和同步 (sync) 操作。要防止锁定和同步，请使用 --frozen；或者仅防止同步，使用 --no-sync。

发布你的包

注意

从 GitHub Actions 发布到 PyPI 的完整指南可以在 GitHub 指南中找到

使用 uv publish 发布你的包

$ uv publish

通过 --token 或 UV_PUBLISH_TOKEN 设置 PyPI 令牌，或者通过 --username 或 UV_PUBLISH_USERNAME 设置用户名，并通过 --password 或 UV_PUBLISH_PASSWORD 设置密码。如果从 GitHub Actions 或其他受信任的发布者 (Trusted Publisher) 发布到 PyPI，则无需设置任何凭据。此时，请将受信任的发布者添加到 PyPI 项目中。

注意

PyPI 不再支持使用用户名和密码进行发布，你需要改为生成令牌。使用令牌等同于设置 --username __token__ 并将令牌作为密码使用。

如果你通过 [[tool.uv.index]] 使用了自定义索引，请添加 publish-url 并使用 uv publish --index <name>。例如

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
explicit = true

注意

当使用 uv publish --index <name> 时，必须存在 pyproject.toml，即你需要在一个发布 CI 作业中执行签出 (checkout) 步骤。

尽管 uv publish 会重试失败的上传，但仍可能发生发布过程中途失败，导致部分文件已上传而部分缺失的情况。对于 PyPI，你可以重新运行相同的命令，已存在的相同文件将被忽略。对于其他仓库，请使用 --check-url <index url> 并指定索引 URL（而非发布 URL）。使用 --index 时，索引 URL 会自动用作检查 URL。uv 将跳过上传与仓库中已有文件完全相同的文件，并处理并发上传竞争。请注意，现有文件必须与之前上传到仓库的文件完全一致，这可以避免意外为同一版本发布内容不同的源码包和 wheel。

随包上传证明 (Attestations)

注意

某些第三方包索引可能不支持证明 (attestations)，并可能拒绝包含它们的上传（而不是静默忽略）。如果在上传时遇到问题，可以使用 --no-attestations 或 UV_PUBLISH_NO_ATTESTATIONS 来禁用 uv 的默认行为。

提示

uv publish 目前不会生成证明；证明必须在发布前单独创建。

uv publish 支持将证明 (attestations) 上传到支持它们的仓库，例如 PyPI。

uv 将自动发现并匹配证明。例如，给定以下 dist/ 目录，uv publish 会将证明与其对应的分发包一起上传

$ ls dist/
hello_world-1.0.0-py3-none-any.whl
hello_world-1.0.0-py3-none-any.whl.publish.attestation
hello_world-1.0.0.tar.gz
hello_world-1.0.0.tar.gz.publish.attestation

安装你的包

使用 uv run 测试该包是否可以安装和导入

$ uv run --with <PACKAGE> --no-project -- python -c "import <PACKAGE>"

--no-project 标志用于避免从你的本地项目目录安装该包。

提示

如果你最近安装过该包，可能需要包含 --refresh-package <PACKAGE> 选项，以避免使用该包的缓存版本。

下一步

要了解关于发布包的更多信息，请查阅 PyPA 关于构建和发布指南。

或者，继续阅读关于将 uv 与其他软件集成的指南。