Poetry Dynamic Versioning

1.10.0 · active · verified Thu Apr 09

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.

Warnings

breaking Older installation methods relying on a `.pth` hack for Poetry versions < 1.2.0 (e.g., global `pip install` without the plugin system) are no longer officially supported by current versions of `poetry-dynamic-versioning`.
Fix: 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`.
gotcha Incorrect `pyproject.toml` configuration, particularly regarding the presence or absence of `project.dynamic`, `project.version`, `tool.poetry.name`, and `tool.poetry.version`, can prevent the plugin from working correctly.
Fix: 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.
gotcha Projects with complex file substitution patterns may encounter issues due to inconsistent path resolution between `tool.poetry-dynamic-versioning.files` and `tool.poetry-dynamic-versioning.substitution.files`. This was a known issue fixed in v1.9.1.
Fix: 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.
gotcha In monorepos with inter-dependent modules, Poetry resolves dependency version constraints *before* `poetry-dynamic-versioning` performs its text substitution. This means if a module depends on another module within the monorepo, and its version is set as a placeholder (e.g., '0.0.0') in `pyproject.toml`, Poetry's initial resolution step might fail.
Fix: 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.

Install

# 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-versioning Install Plugin

Imports

Not Applicable
```
This is a Poetry plugin and is configured via pyproject.toml and CLI commands, not direct Python imports in user code.
```
Poetry plugins are generally not imported directly by user applications. Their functionality is integrated into the Poetry CLI or build process.

Quickstart

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.

# 1. Install the plugin (see 'Install' section for options based on your Poetry version)
# For Poetry 1.2.0+:
pip install poetry-dynamic-versioning

# 2. Navigate to your project directory
# cd your-project

# 3. Enable dynamic versioning for your project
poetry dynamic-versioning enable

# This command updates your pyproject.toml to look like this (simplified):
# [project]
# dynamic = ["version"]
# name = "your-project-name"
#
# [tool.poetry]
# version = "0.0.0" # Placeholder
#
# [tool.poetry-dynamic-versioning]
# enable = true

# 4. Create an initial Git tag
git init
git add .
git commit -m "Initial commit"
git tag v0.1.0

# 5. Build your project to see the dynamic version in action
poetry build

view raw JSON →