构建和发布软件包

uv 支持使用 uv build 将 Python 软件包构建为源代码和二进制分发包，并使用 uv publish 将它们上传到注册表。

准备项目以进行打包

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

如果您的项目在 pyproject.toml 中不包含 [build-system] 定义，则 uv 默认不会构建它。 这意味着您的项目可能尚未准备好进行分发。 阅读有关在项目概念文档中声明构建系统的影响的更多信息。

注意

如果您有不想发布的内部软件包，您可以将它们标记为私有

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

此设置会使 PyPI 拒绝您上传的软件包进行发布。 它不会影响备用注册表上的安全或隐私设置。

我们还建议仅生成 每个项目的 PyPI API 令牌：如果没有与项目匹配的 PyPI 令牌，则不会意外发布。

构建软件包

使用 uv build 构建软件包

$ uv build

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

或者，uv build <SRC> 将在指定目录中构建软件包，而 uv build --package <PACKAGE> 将在当前工作区中构建指定的软件包。

信息

默认情况下，当从 pyproject.toml 的 build-system.requires 部分解析构建依赖项时，uv build 会遵循 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）。

要从稳定版本移动到预发布版本，除了预发布组件之外，还要增加主要、次要或补丁组件之一

$ 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.1b2

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

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

信息

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

发布软件包

使用 uv publish 发布软件包

$ uv publish

使用 --token 或 UV_PUBLISH_TOKEN 设置 PyPI 令牌，或使用 --username 或 UV_PUBLISH_USERNAME 设置用户名，并使用 --password 或 UV_PUBLISH_PASSWORD 设置密码。 要从 GitHub Actions 发布到 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。

安装软件包

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

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

--no-project 标志用于避免从本地项目目录安装软件包。

提示

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

下一步

要了解有关发布软件包的更多信息，请查看有关构建和发布的 PyPA 指南。

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