VCS Versioning

1.1.1 verified Tue May 12 auth: no python install: stale

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.

pip install vcs-versioning

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.

breaking The `get_version` function is no longer directly importable from the top-level `vcs_versioning` package. This function has been internalized or moved within `vcs-versioning`, and the public API for retrieving versions is primarily exposed through `setuptools_scm.get_version`. ↓

fix Change import statements from `from vcs_versioning import get_version` to `from setuptools_scm import get_version`. Ensure `setuptools-scm` is installed and used as the primary interface for version retrieval.

Install compatibility stale last tested: 2026-05-12 v0.0.1 installed · v1.1.1 latest

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - - 19.6M - broken

3.10 alpine (musl) - - - - - -

3.10 slim (glibc) wheel 1.7s - 20M - broken

3.10 slim (glibc) - - - - - -

3.11 alpine (musl) wheel - - 21.2M - broken

3.11 alpine (musl) - - - - - -

3.11 slim (glibc) wheel 1.7s - 22M - broken

3.11 slim (glibc) - - - - - -

3.12 alpine (musl) wheel - - 13.0M - broken

3.12 alpine (musl) - - - - - -

3.12 slim (glibc) wheel 1.6s - 14M - broken

3.12 slim (glibc) - - - - - -

3.13 alpine (musl) wheel - - 12.8M - broken

3.13 alpine (musl) - - - - - -

3.13 slim (glibc) wheel 1.6s - 13M - broken

3.13 slim (glibc) - - - - - -

3.9 alpine (musl) wheel - - 17.3M - broken

3.9 alpine (musl) - - - - - -

3.9 slim (glibc) wheel 1.7s - 18M - broken

3.9 slim (glibc) - - - - - -

Imports

get_version
wrong
```
from setuptools_scm import get_version
```
correct
```
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 last tested: 2026-04-24

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}")