Skip to content

Overrides

For Integrators

If you're building a tool that integrates vcs-versioning (like hatch-vcs), see the Integrator Guide for using the overrides API with custom prefixes and the GlobalOverrides context manager.

About Overrides

Environment variables provide runtime configuration overrides, primarily useful in CI/CD environments where you need different behavior without modifying pyproject.toml or code.

All environment variables support both SETUPTOOLS_SCM_* and VCS_VERSIONING_* prefixes. The VCS_VERSIONING_* prefix serves as a universal fallback that works across all tools using vcs-versioning.

Configuration Priority

When building a Configuration, settings are merged in this priority order (highest wins):

  1. Environment TOML overrides -- TOOL_OVERRIDES_FOR_DIST / TOOL_OVERRIDES
  2. Per-project overrides -- .config/python-vcs-versioning.toml in the SCM root
  3. Integrator keyword arguments -- e.g. kwargs from build_configuration_from_pyproject
  4. pyproject.toml section -- [tool.setuptools_scm] or [tool.vcs-versioning]
  5. Defaults -- built-in vcs-versioning defaults

Version Resolution Pipeline

Once configuration is built, the version is resolved in this order:

  1. Pretend version -- TOOL_PRETEND_VERSION / _FOR_DIST short-circuits everything
  2. Workdir discovery -- discover_workdir(config) tries:
    • config.parse callback (legacy, deprecated) -- highest priority within discovery
    • Registered vcs_versioning.discover_workdir entry-point factories (git, hg, etc.)
    • Fallback workdirs (archival files, PKG-INFO, static fallback)
  3. Legacy parse entry points -- setuptools_scm.parse_scm / parse_scm_fallback (third-party only)
  4. Metadata overrides -- TOOL_PRETEND_METADATA / _FOR_DIST applied on top of resolved version
  5. Format -- version_scheme + local_scheme produce the final version string

Version Detection Overrides

Pretend Versions

Override the version number at build time.

setuptools-scm usage:

The environment variable SETUPTOOLS_SCM_PRETEND_VERSION (or VCS_VERSIONING_PRETEND_VERSION) is used as the override source for the version number unparsed string.

it is strongly recommended to use distribution-specific pretend versions (see below).

SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DIST_NAME} or VCS_VERSIONING_PRETEND_VERSION_FOR_${DIST_NAME}

Used as the primary source for the version number, in which case it will be an unparsed string. Specifying distribution-specific pretend versions will avoid possible collisions with third party distributions also using vcs-versioning.

The dist name normalization follows adapted PEP 503 semantics, with one or more of ".-_" being replaced by a single "_", and the name being upper-cased.

This will take precedence over the generic SETUPTOOLS_SCM_PRETEND_VERSION or VCS_VERSIONING_PRETEND_VERSION.

Pretend Metadata

Override individual version metadata fields at build time.

setuptools-scm usage:

SETUPTOOLS_SCM_PRETEND_METADATA
Accepts a TOML inline table with field overrides for the ScmVersion object.
SETUPTOOLS_SCM_PRETEND_METADATA_FOR_${DIST_NAME}
Same as above but specific to a package (recommended over the generic version). The dist name normalization follows adapted PEP 503 semantics.

Supported fields

The following ScmVersion fields can be overridden:

  • distance (int): Number of commits since the tag
  • node (str): The commit hash/node identifier
  • dirty (bool): Whether the working directory has uncommitted changes
  • branch (str): The branch name
  • node_date (date): The date of the commit (TOML date format: 2024-01-15)
  • time (datetime): The version timestamp (TOML datetime format)
  • preformatted (bool): Whether the version string is preformatted
  • tag: The version tag (can be string or version object)

Examples

Override commit hash and distance: 

export SETUPTOOLS_SCM_PRETEND_METADATA='{node="g1337beef", distance=4}'

Override multiple fields with proper TOML types: 

export SETUPTOOLS_SCM_PRETEND_METADATA='{node="gabcdef12", distance=7, dirty=true, node_date=2024-01-15}'

Use with a specific package: 

export SETUPTOOLS_SCM_PRETEND_METADATA_FOR_MY_PACKAGE='{node="g1234567", distance=2}'

Node ID Prefixes

Node IDs must include the appropriate SCM prefix:

  • Use g prefix for Git repositories (e.g., g1a2b3c4d5)
  • Use h prefix for Mercurial repositories (e.g., h1a2b3c4d5)

This ensures consistency with setuptools-scm's automatic node ID formatting.

Use case: CI/CD environments

This is particularly useful for solving issues where version file templates need access to commit metadata that may not be available in certain build environments:

[tool.setuptools_scm]
version_file = "src/mypackage/_version.py"
version_file_template = '''
version = "{version}"
commit_hash = "{scm_version.node}"
commit_count = {scm_version.distance}
'''

With pretend metadata, you can ensure the template gets the correct values: 

export SETUPTOOLS_SCM_PRETEND_VERSION="1.2.3.dev4+g1337beef"
export SETUPTOOLS_SCM_PRETEND_METADATA='{node="g1337beef", distance=4}'

Debug Logging

Enable debug output from vcs-versioning.

setuptools-scm usage:

SETUPTOOLS_SCM_DEBUG or VCS_VERSIONING_DEBUG
Enable debug logging for version detection and processing. Can be set to: - 1 or any non-empty value to enable DEBUG level logging - A level name: DEBUG, INFO, WARNING, ERROR, or CRITICAL (case-insensitive) - A specific log level integer: 10 (DEBUG), 20 (INFO), 30 (WARNING), etc. - 0 to disable debug logging

Reproducible Builds

Control timestamps for reproducible builds (from reproducible-builds.org).

SOURCE_DATE_EPOCH
Used as the timestamp from which the node-and-date and node-and-timestamp local parts are derived, otherwise the current time is used. This is a standard environment variable supported by many build tools.

setuptools-scm Overrides

Configuration Overrides

SETUPTOOLS_SCM_OVERRIDES_FOR_${DIST_NAME}

A TOML inline table to override configuration from pyproject.toml. This allows overriding any configuration option at build time, which is particularly useful in CI/CD environments where you might want different behavior without modifying pyproject.toml.

Example: 

# Override local_scheme for CI builds
export SETUPTOOLS_SCM_OVERRIDES_FOR_MYPACKAGE='{local_scheme = "no-local-version-strict"}'

Fail on uncommitted changes in release CI

The simplest way to enforce a clean tree and strip local segments for PyPI uploads is no-local-version-strict:

export SETUPTOOLS_SCM_OVERRIDES_FOR_MYPACKAGE='{local_scheme = "no-local-version-strict"}'

This fails the build when the working tree is dirty and otherwise produces a version without a local segment — exactly what release CI needs.

If you need a different fallback local scheme (e.g. node-and-date instead of stripping the local part), use a list whose first entry is fail-on-uncommitted-changes and whose second entry is your usual scheme:

export SETUPTOOLS_SCM_OVERRIDES_FOR_MYPACKAGE='{local_scheme = ["fail-on-uncommitted-changes", "node-and-date"]}'

These overrides take precedence over [tool.setuptools_scm] / [tool.vcs-versioning] in pyproject.toml (see priority under About Overrides).

Use the distribution-specific variable so the override applies only to your package (the name is normalized the same way as for other *_FOR_${DIST_NAME} variables; see integrations).

If you use [tool.vcs-versioning] (and not setuptools-scm), set the same TOML value on VCS_VERSIONING_OVERRIDES_FOR_${DIST_NAME} instead, for example:

export VCS_VERSIONING_OVERRIDES_FOR_MYPACKAGE='{local_scheme = "no-local-version-strict"}'

GitHub Actions: set env on the job or step that builds release artifacts:

env:
  SETUPTOOLS_SCM_OVERRIDES_FOR_MYPACKAGE: '{local_scheme = "no-local-version-strict"}'

SCM Root Discovery

SETUPTOOLS_SCM_IGNORE_VCS_ROOTS
A os.pathsep separated list of directory names to ignore for root finding.

Mercurial Command

SETUPTOOLS_SCM_HG_COMMAND
Command used for running Mercurial (defaults to hg). For example, set this to chg to reduce start-up overhead of Mercurial.

Subprocess Timeouts

SETUPTOOLS_SCM_SUBPROCESS_TIMEOUT

Override the subprocess timeout (default: 40 seconds). The default should work for most needs. However, users with git lfs + windows reported situations where this was not enough.

Example: 

# Increase timeout to 120 seconds
export SETUPTOOLS_SCM_SUBPROCESS_TIMEOUT=120