---
id: poetry-dynamic-versioning
version: "1.10.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# poetry-dynamic-versioning — Plugin for Poetry to enable dynamic versioning based on VCS tags

License: permissive · Maintenance: active · Downloads: 4.0M/mo

## What it is and what it does

poetry-dynamic-versioning is a Poetry plugin that automatically derives your project's version from version control tags at build time. Instead of manually maintaining a version string in pyproject.toml, you tag your repository (e.g., `git tag v1.0.0`), and the plugin reads that tag, injects the version into your build artifacts, then cleans up so your working directory stays unchanged. It uses Dunamai under the hood to parse tags from Git, Mercurial, and several other VCS systems, and supports custom tag patterns and version formatting via regular expressions or Jinja templates.

The plugin integrates with Poetry's build system at two levels: as a PEP 517 build backend for compatibility with other build frontends, and as a Poetry CLI command for direct integration with `poetry build` and related commands. Configuration is minimal—enable it in pyproject.toml, set your VCS and tag pattern if needed, and the plugin handles the rest. It's designed for projects that want version numbers to stay in sync with their release tags without manual edits or commits.

Use it for:

- Automatically version Python packages from Git tags in CI/CD pipelines without editing pyproject.toml.
- Maintain a clean repository by keeping version strings as placeholders and deriving real versions at build time.
- Support multiple VCS systems (Git, Mercurial, etc.) with a single configuration.
- Inject custom version metadata (commit hash, dirty flag, branch name) into build artifacts using Jinja templates.
- Ensure build artifacts always reflect the exact VCS state they were built from, improving reproducibility.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Poetry plugin that automatically derives and injects version numbers from version control tags into your project during builds, using Dunamai to support multiple VCS systems.

Yes. This is a stable, actively maintained plugin with no known vulnerabilities, low install friction, and a clear use case for projects that want version control to be the single source of truth for versioning. Install it if you use Poetry 1.2.0+ and want to eliminate manual version management in your build workflow.

## Install

pip install poetry-dynamic-versioning
uv add poetry-dynamic-versioning
poetry add poetry-dynamic-versioning

## Installing poetry-dynamic-versioning

Before you install: Low friction install via Poetry's plugin system. Actively maintained with recent commits and no known vulnerabilities. Requires Poetry 1.2.0+ and Python 3.7+.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

# Install with plugin support
poetry self add "poetry-dynamic-versioning[plugin]"

# Enable in your project
poetry dynamic-versioning enable

# Or manually add to pyproject.toml:
# [tool.poetry-dynamic-versioning]
# enable = true

# Then tag your repo and build
git tag v1.0.0
poetry build

Requires Poetry 1.2.0+ and a supported VCS (Git, Mercurial, Darcs, Bazaar, Subversion, Fossil, or Pijul) with at least one version tag present.

Verify before relying:

- Whether the plugin works seamlessly with all Poetry 2.0+ workflows beyond the documented install path.
- Performance impact on large projects or repositories with many tags.
- Compatibility with monorepo setups or projects with multiple pyproject.toml files.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 4.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

poetry dynamic versioning plugin, automatic version from git tags, poetry vcs-based versioning, dynamic version control tagging, poetry build version injection, dunamai poetry integration, automatic semantic versioning poetry, poetry-plugin, vcs-versioning, build-automation

[View on SkillFed](https://skillfed.io/packages/poetry-dynamic-versioning) · [View on PyPI](https://pypi.org/project/poetry-dynamic-versioning/)