VCS Versioning

1.1.1 · active · verified Wed Apr 01

vcs-versioning is a Python library that provides core version inference logic based on Version Control System (VCS) metadata. It serves as a foundational component for build backends like setuptools-scm, enabling projects to automatically derive their package version from Git tags, branches, and commit information. The library is currently at version 1.1.1 and follows an active release cadence, often in conjunction with its primary consumer, setuptools-scm.

Warnings

breaking vcs-versioning, as a core dependency introduced by setuptools-scm v10.0.0, drops support for Python 3.8 and 3.9. Minimum Python version is now 3.10.
Fix: Upgrade your Python environment to 3.10 or newer.
breaking The behavior for writing version files (`write_to` and `version_file`) changed in setuptools-scm v10.0.0 (which incorporated vcs-versioning). Version files are now written to the build directory by default, not the source tree. This affects how build tools locate generated version information.
Fix: To revert to writing version files to the source tree, set the environment variable `SETUPTOOLS_SCM_WRITE_TO_SOURCE=1`. For editable installs, ensure build outputs are correctly registered.
deprecated The `dump_version()` function is deprecated. Users should migrate away from its direct use.
Fix: Avoid direct calls to `dump_version()`. If specific version file generation is needed, consider alternative approaches or rely on the build system's automatic version file handling.
gotcha Shallow Git worktrees and exact-match tagged releases no longer trigger `warn_on_shallow` or `fail_on_shallow` behavior as of v1.1.0, as these are now considered sufficient for tagged release builds.
Fix: Review build pipelines that previously relied on shallow clone warnings for tagged releases; they might no longer be triggered. Adjust logic if specific shallow clone checks are still required in these scenarios.
gotcha When using `get_version` directly in complex project structures (e.g., monorepos or workspaces), ensure `root`, `relative_to`, and `fallback_root` arguments are correctly anchored. Incorrect paths can lead to version inference resolving against the wrong directory or falling back unexpectedly.
Fix: Always explicitly specify the `root` argument and carefully consider `relative_to` and `fallback_root` for accurate version resolution, especially when the build CWD is not the project root.

Install

pip install vcs-versioning Install latest version

Imports

get_version
```
from vcs_versioning import get_version
```
While setuptools_scm.get_version is the common interface for setuptools projects, vcs-versioning directly exposes get_version for other build backends.
ScmVersion
```
from vcs_versioning import ScmVersion
```

Quickstart

This snippet demonstrates how to directly use `vcs_versioning.get_version` to infer a project's version from its VCS metadata. It attempts to find the version for the current directory, providing a fallback for environments without a detected VCS.

import os
from vcs_versioning import get_version

# To demonstrate, this will try to get the version of the current directory.
# For a real project, run this inside a Git repository.
# The fallback_version is provided to make it runnable outside a VCS context.
try:
    project_version = get_version(root=".", fallback_version="0.0.0+unknown.version")
    print(f"Project version: {project_version}")
except Exception as e:
    print(f"Could not determine project version: {e}")

view raw JSON →