Poetry Dynamic Versioning is a plugin for Poetry (1.2.0+ and Poetry Core 1.0.0+) that enables dynamic versioning for Python projects based on tags in your version control system. It is powered by the Dunamai library and automatically inserts the correct version into relevant files during Poetry commands (like `poetry build`), reverting changes afterward to keep the repository clean. The current version is 1.10.0, and it maintains an active release cadence.
# For Poetry 2.0.0+
poetry add --group dev poetry-dynamic-versioning --extras plugin
# For Poetry 1.2.0+ (manual installation if not using plugin system)
pip install poetry-dynamic-versioningNo compatibility data collected yet for this library.
Verified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to install the plugin, enable dynamic versioning for a project via the CLI command, and create a Git tag for version detection. The `poetry dynamic-versioning enable` command automatically configures `pyproject.toml` for you. Building the project will then use the version from your Git tag.
Migrate to Poetry 1.2.0+ and install `poetry-dynamic-versioning` using the official plugin system (via `poetry add --group dev poetry-dynamic-versioning --extras plugin`) or by manually installing the package with `pip install` in an environment accessible to your Poetry installation and then using `poetry dynamic-versioning enable`.
Ensure your `pyproject.toml` explicitly sets `[project] dynamic = ["version"]` and `[tool.poetry] version = "0.0.0"` (as a placeholder). If using PEP 621 mode, avoid `tool.poetry.name` and `project.version`. The `poetry dynamic-versioning enable` command can help set up the initial configuration correctly. Refer to the official documentation for detailed configuration requirements for classic vs. PEP 621 modes.
Upgrade to `poetry-dynamic-versioning` v1.9.1 or newer to benefit from the fix. When specifying file paths for substitution, ensure consistent relative path styles.
Consider alternatives for monorepo setups, such as using Poetry workspaces with path dependencies for local development, or ensuring that inter-module dependencies are explicitly versioned in a way that allows Poetry to resolve them initially, possibly by managing versions centrally or using a build process that handles this sequencing. Consult GitHub issues (e.g., #189) for ongoing discussions and potential workarounds.
Uninstall `poetry-dynamic-versioning` if installed with `pip --user`, then upgrade Poetry to version 1.2.0 or newer. For Poetry 1.2.0+, install the plugin using `poetry self add "poetry-dynamic-versioning[plugin]"`. For Poetry 2.0.0+, declare the plugin in `pyproject.toml` under `[tool.poetry.requires-plugins]` and run `poetry install`.
Ensure your `pyproject.toml` specifies `project.name`, `project.dynamic = ["version"]`, and `tool.poetry.version = "0.0.0"` as a placeholder. Crucially, do not define `project.version` when using dynamic versioning with PEP-621.
For Poetry 2.0.0+, ensure the `pyproject.toml` contains the plugin declaration under `[tool.poetry.requires-plugins]` and then run `poetry install`. For older Poetry versions (1.2.0+), install the plugin directly into Poetry's environment using `poetry self add "poetry-dynamic-versioning[plugin]"`.