{"id":1857,"library":"poetry-dynamic-versioning","title":"Poetry Dynamic Versioning","description":"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.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/mtkennerly/poetry-dynamic-versioning","tags":["poetry","plugin","versioning","vcs","build","automation"],"install":[{"cmd":"# For Poetry 2.0.0+\npoetry add --group dev poetry-dynamic-versioning --extras plugin\n\n# For Poetry 1.2.0+ (manual installation if not using plugin system)\npip install poetry-dynamic-versioning","lang":"bash","label":"Install Plugin"}],"dependencies":[{"reason":"Core library for version detection logic.","package":"dunamai","optional":false},{"reason":"Host application for the plugin.","package":"poetry","optional":false},{"reason":"Required if using Git as the Version Control System for dynamic versioning.","package":"git","optional":true}],"imports":[{"note":"Poetry plugins are generally not imported directly by user applications. Their functionality is integrated into the Poetry CLI or build process.","symbol":"Not Applicable","correct":"This is a Poetry plugin and is configured via pyproject.toml and CLI commands, not direct Python imports in user code."}],"quickstart":{"code":"# 1. Install the plugin (see 'Install' section for options based on your Poetry version)\n# For Poetry 1.2.0+:\npip install poetry-dynamic-versioning\n\n# 2. Navigate to your project directory\n# cd your-project\n\n# 3. Enable dynamic versioning for your project\npoetry dynamic-versioning enable\n\n# This command updates your pyproject.toml to look like this (simplified):\n# [project]\n# dynamic = [\"version\"]\n# name = \"your-project-name\"\n#\n# [tool.poetry]\n# version = \"0.0.0\" # Placeholder\n#\n# [tool.poetry-dynamic-versioning]\n# enable = true\n\n# 4. Create an initial Git tag\ngit init\ngit add .\ngit commit -m \"Initial commit\"\ngit tag v0.1.0\n\n# 5. Build your project to see the dynamic version in action\npoetry build","lang":"bash","description":"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."},"warnings":[{"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`.","message":"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`.","severity":"breaking","affected_versions":"<=0.17.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.9.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}