PyPI

On this page

Publish
Pending

Publish

uv supports building Python packages into source and binary distributions via uv build and uploading them to a registry with uv publish.

Preparing your project

Before attempting to publish your project, you’ll want to make sure it’s ready to be packaged for distribution.

Configure a build system for your project.

This is done by adding a [build-system] table to your pyproject.toml file.

For example:

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

If your project does not include a [build-system] definition in the pyproject.toml, uv will not build it during uv sync operations in the project, but will fall back to the legacy setuptools build system during uv build.

Read more about build systems in the project configuration documentation.

Building your package

Build your package with uv build:

uv build

By default, uv build will build the project in the current directory, and place the built artifacts in a dist/ subdirectory.

Alternatively, uv build <SRC> will build the package in the specified directory, while uv build --package <PACKAGE> will build the specified package within the current workspace.

By default, uv build respects tool.uv.sources when resolving build dependencies from the build-system.requires section of the pyproject.toml. When publishing a package, we recommend running uv build --no-sources to ensure that the package builds correctly when tool.uv.sources is disabled, as is the case when using other build tools, like pypa/build.

Updating your version

The uv version command provides conveniences for updating the version of your package before you publish it.

To get the version of your package, run uv version:

uv version

To update to an exact version, provide it as a positional argument:

uv version 1.0.0

To preview the change without updating the pyproject.toml, use the --dry-run flag:

uv version 2.0.0 --dry-run

To increase the version of your package semantics, use the --bump option:

uv version --bump minor

The --bump option supports the following common version components: major, minor, patch, stable, alpha, beta, rc, post, and dev. When provided more than once, the components will be applied in order, from largest (major) to smallest (dev).

You can optionally provide a numeric value with --bump <component>=<value> to set the resulting component explicitly:

uv version --bump patch --bump dev=66463664

To move from a stable to pre-release version, bump one of the major, minor, or patch components in addition to the pre-release component:

uv version --bump patch --bump beta
uv version --bump major --bump alpha

When moving from a pre-release to a new pre-release version, just bump the relevant pre-release component:

uv version --bump beta

When moving from a pre-release to a stable version, the stable option can be used to clear the pre-release component:

uv version --bump stable

By default, when uv version modifies the project it will perform a lock and sync . To prevent locking and syncing, use --frozen, or, to just prevent syncing, use --no-sync.

Publishing your package

Publish your package with uv publish:

uv publish

Set a PyPI token with --token or UV_PUBLISH_TOKEN.

For publishing to PyPI from Trusted Publisher, you don’t need to set any credentials. Instead, add a trusted publisher to the PyPI project.

Even though uv publish retries failed uploads, it can happen that publishing fails in the middle, with some files uploaded and some files still missing. With PyPI, you can retry the exact same command, existing identical files will be ignored.

A complete guide to publishing from GitHub Actions to PyPI can be found in the GitHub Guide

Finally, tag a release and push it.

Make sure it starts with v to match the pattern in the workflow.

tag -a v0.1.0 -m v0.1.0
push --tags

Local install

Install the locally built isard wheel package

$ uv tool install ./dist/isard-0.1.1-py3-none-any.whl --force

Manual upload:

uv build
uv run twine upload dist/* --username __token__

Python - PyPI