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_TOKENwith--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, inUV_PUBLISH_TOKEN(usually the production token, so it is never used for TestPyPI), handed touv publishthrough its environment so it never appears on the command line.uv publishruns with the environment of the process minusUV_PUBLISH_TOKEN,UV_PUBLISH_USERNAMEandUV_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: writepermission (--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¶
invoke_tasklib.releasereference- Troubleshooting: fixes for
PYPI_TOKENauthentication errors.