Skip to content

Release

📖 This page describes the invoke_tasklib.release module, which provides tasks to build and publish the package to PyPI using uv.

Overview

Task Behavior
release.build Builds the package and verifies installation (--check also validates metadata with twine)
release.publish Checks the git state, then builds and publishes the package to PyPI or TestPyPI

Building

invoke release.build

Runs uv build, then verifies the artifacts it produced: the newest wheel and the newest source distribution in dist/ are each installed in an isolated uv run environment (uv run --isolated --no-project --with dist/<file>) and the package is imported from it with python -I (isolated mode: the current directory is not on sys.path, so a package of the source tree in a flat layout cannot hide an artifact that does not contain it). The task fails if the build did not produce a wheel or a source distribution. With --wheel or --sdist in --args, only that kind is verified, and with --out-dir <dir> (or -o) the files of <dir> are verified (and checked by --check) instead of dist/.

Pass --check to additionally validate the package's PyPI metadata with twine check:

invoke release.build --check

twine is run with uvx from the version range twine>=7,<8 (_TWINE_REQUIREMENT in invoke_tasklib.release), so a new major release is never run without a release of invoke-tasklib.

Publishing to PyPI

invoke release.publish

Before anything is built, the task checks the git state: the working tree must be clean, HEAD must be tagged and the tag (without a leading v) must be the static project.version of pyproject.toml (a dynamic version is not compared; an invalid pyproject.toml stops the task with a message that names the file). It then asks for a confirmation, unless --yes is given or the CI environment variable is set to something other than 0 and false. Finally it builds the package (via release.build with its defaults, which clears dist/ first so stale artifacts are never uploaded) and runs uv publish. --args is given to uv publish only, not to the build.

Credentials, in this order:

  • a token in PYPI_TOKEN (TEST_PYPI_TOKEN with --test-pypi, because the two indexes reject each other's tokens and a PyPI token must not be sent to TestPyPI) or, without --test-pypi, in UV_PUBLISH_TOKEN (usually the production token, so it is never used for TestPyPI), handed to uv publish through its environment so it never appears on the command line. uv publish runs with the environment of the process minus UV_PUBLISH_TOKEN, UV_PUBLISH_USERNAME and UV_PUBLISH_PASSWORD (only the chosen token is added), so a token that the job defines for PyPI is not inherited by a TestPyPI upload;
  • PyPI Trusted Publishing (OpenID Connect), used automatically in GitHub Actions with the id-token: write permission (--trusted-publishing always); no token is needed.

Without either, the task fails before building.

Option Effect
--test-pypi Publishes to TestPyPI instead of PyPI
--dry-run Runs the checks and the build, and gives --dry-run to uv publish; no token
--yes Does not ask for a confirmation
--skip-checks Does not check the git state
--args Extra arguments for uv publish
invoke release.publish --dry-run
invoke release.publish --test-pypi --yes

Warning

This publishes a new version to PyPI, which cannot be undone. Try --dry-run or --test-pypi first, and make sure you are releasing the intended version.

release.build takes --args for uv build.

See Also