dunamai

library1.26.2pypypi✓ verified 26d ago

Dunamai is a Python 3.5+ library and command-line tool for producing dynamic, standards-compliant version strings, derived from tags in your version control system (Git, Mercurial, Darcs, Subversion, Bazaar, Fossil, Pijul). It facilitates uniquely identifying nightly or per-commit builds in continuous integration and simplifying releases by creating a tag. It supports various version styles like PEP 440 and Semantic Versioning, or custom formats. Dunamai, currently at version 1.26.1, maintains an active development and release cadence.

devops

pip install dunamai

github ↗package ↗

INSTALL

IMPORT

SIG · DUNAMAI

dunamai

devopspythonv1.26.2

Install

1.7s avg

Import

167ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.26.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.176s · 18.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.158s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Version

✓ from dunamai import Version

Style

✓ from dunamai import Style

Pattern

✓ from dunamai import Pattern

Used for predefined version tag patterns.

This example demonstrates how to retrieve and serialize a dynamic version string from any detected VCS. It includes options for fallback versions and strict mode, which are crucial for robust integration in varied environments like CI/CD pipelines. The output can be formatted according to different versioning styles.

import os from dunamai import Version # In a Git repository with tag v0.1.0 and some commits after it try: version = Version.from_any_vcs( # Optional: Specify a fallback version if no VCS is found or no tags match. # Defaults to '0.0.0' if not strict, or raises an error if strict. fallback=os.environ.get("DUNAMAI_FALLBACK_VERSION", "0.0.0"), # Optional: Set strict=True to raise an error if a version cannot be determined. # Default is False, which may use fallback. strict=bool(os.environ.get("DUNAMAI_STRICT", "").lower() == "true"), ) # Prints a PEP 440 compliant version like "0.1.0.post7.dev0+g29045e8" print(f"Current version: {version.serialize()}") # Or a Semantic Versioning compliant string like "0.1.0-post.7" print(f"Semantic version: {version.serialize(style='semver', metadata=False)}") except RuntimeError as e: print(f"Could not determine version: {e}") # Handle cases where version cannot be determined (e.g., not in a VCS repo)

dunamai --version

Debug

Known issues

breakingThe `Version.__lt__` comparison logic was fixed in v1.23.1. Prior to this, `Version.__lt__` incorrectly checked if *all* fields were less, rather than using proper field precedence for version ordering. This could lead to incorrect comparisons between `Version` instances.

fix

Upgrade to `dunamai` v1.23.1 or newer to ensure correct version comparison behavior.

affects: <1.23.1

gotchaDunamai requires access to the full version history to accurately find tags and compute distance. CI systems often perform shallow clones by default, which can prevent Dunamai from determining the correct version.

fix

Ensure your CI environment performs a full clone. For GitHub Actions, use `actions/checkout@v3` with `fetch-depth: 0`. For GitLab, set `GIT_DEPTH` to `0`.

affects: All versions

gotchaSetting the `GIT_TRACE` environment variable can cause `Version.from_git` to fail due to unexpected output from Git commands.

fix

Upgrade to `dunamai` v1.23.2 or newer, which includes a fix for this issue. Alternatively, ensure `GIT_TRACE` is not set when running `dunamai`.

affects: <1.23.2

gotchaThe `highest_tag` argument, intended to select the numerically highest version tag, was ignored in `Version.from_any_vcs()` and related functions.

fix

Upgrade to `dunamai` v1.26.1 or newer to correctly utilize the `highest_tag` functionality.

affects: 1.26.0

gotchaUsing lightweight Git tags (instead of annotated tags) or having an initial commit that is both tagged and empty can lead to unreliable tag detection and sorting, as Git does not store creation times for lightweight tags and has reporting issues with empty, tagged initial commits.

fix

Prefer annotated tags (`git tag -a`) over lightweight tags. Avoid tagging the initial empty commit (created with `--allow-empty`).

affects: All versions

breakingAttempting to use the `fallback` keyword argument with `Version.from_any_vcs()` in versions prior to `v1.24.0` will result in a `TypeError` because the argument was not yet supported.

fix

Upgrade to `dunamai` v1.24.0 or newer to use the `fallback` argument with `from_any_vcs()`.

affects: <1.24.0

breakingCalling `Version.from_any_vcs()` with the `fallback` keyword argument will raise a `TypeError` if `dunamai` is older than v1.23.0, as this argument was introduced in v1.23.0.

fix

Upgrade `dunamai` to v1.23.0 or newer to correctly use the `fallback` argument in `Version.from_any_vcs()`.

affects: <1.23.0

Errors

Common errors & fixes

RuntimeError: This does not appear to be a Git project

Dunamai cannot find or access a Git repository (or other configured VCS) in the current directory or specified path.

fix

Ensure you are running Dunamai within a valid Git repository. In CI/CD environments, ensure a full clone (not shallow) is performed, e.g., for GitHub Actions, use `fetch-depth: 0` with `actions/checkout@v3`.

'git' is not recognized as an internal or external command

The Git executable is not found in the system's PATH environment variable, preventing Dunamai from invoking Git commands.

fix

Install Git if it's missing, or add the directory containing the `git` executable (e.g., `C:\Program Files\Git\cmd` and `C:\Program Files\Git\bin` on Windows, or typically `/usr/bin/git` on Linux) to your system's PATH environment variable. Restart your terminal or IDE after modifying PATH.

Version '0.01.0' does not conform to the Semantic Versioning style

The generated or provided version string does not adhere to the rules of the specified versioning style (e.g., PEP 440 or Semantic Versioning) during validation or serialization.

fix

Adjust your project's tags or Dunamai's configuration (e.g., `--format` or `--pattern`) to produce a version string that matches the expected style. For example, Semantic Versioning does not allow leading zeros in major/minor/patch segments.

This is a shallow repository, so Dunamai may not produce the correct version.

Dunamai detected that the Git repository is a shallow clone, meaning it does not contain the full commit history necessary to accurately determine the version from all tags and distances.

fix

In continuous integration (CI) systems, configure the `git clone` command to fetch the full history. For GitHub Actions, set `fetch-depth: 0` in `actions/checkout@v3`. For GitLab CI, set `GIT_DEPTH: 0`.

Upgrade

Version history

1.26.2latest on PyPI · released Aug 2, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/mtkennerly/dunamai ↗

packagehttps://pypi.org/project/dunamai/ ↗