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:
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 buildrespectstool.uv.sourceswhen resolving build dependencies from thebuild-system.requiressection of thepyproject.toml. When publishing a package, we recommend runninguv build --no-sourcesto ensure that the package builds correctly whentool.uv.sourcesis disabled, as is the case when using other build tools, likepypa/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:
To update to an exact version, provide it as a positional argument:
To preview the change without updating the pyproject.toml, use the --dry-run flag:
To increase the version of your package semantics, use the --bump option:
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:
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:
When moving from a pre-release to a new pre-release version, just bump the relevant pre-release component:
When moving from a pre-release to a stable version, the stable option can be used to clear the pre-release component:
By default, when
uv versionmodifies the project it will perform alockandsync. To prevent locking and syncing, use--frozen, or, to just prevent syncing, use--no-sync.
Publishing your package
Publish your package with 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.
Local install
Install the locally built isard wheel package
Manual upload:
uv build
uv run twine upload dist/* --username __token__Pending
- https://docs.astral.sh/uv/guides/package/
- https://realpython.com/pypi-publish-python-package/