Install & Compatibility
Where this runs
tested against v2.3.1 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.260s · 20MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.238s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_version
✓ from vcs_versioning import infer_version_string
✗ from vcs_versioning import get_version
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}")
Debug
Known issues
breakingvcs-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.fixUpgrade your Python environment to 3.10 or newer.
affects: >=1.0.0 (and setuptools-scm >=10.0.0)
breakingThe 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.fixTo 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.
affects: >=1.0.0 (and setuptools-scm >=10.0.0)
deprecatedThe `dump_version()` function is deprecated. Users should migrate away from its direct use.fixAvoid 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.
affects: >=1.0.0 (and setuptools-scm >=10.0.5)
gotchaShallow 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.fixReview 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.
affects: >=1.1.0
gotchaWhen 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.fixAlways 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.
affects: All versions
breakingThe `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`.fixChange 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.
affects: >=1.0.0 (and setuptools-scm >=10.0.0)
Upgrade
Version history
2.3.1latest on PyPI · released Aug 19, 2026
Audit
Dependencies
No dependency data recorded yet.