setuptools-scm 6.4.0

pyproject.toml usage

The preferred way to configure setuptools_scm is to author settings in a tool.setuptools_scm section of pyproject.toml.

This feature requires Setuptools 42 or later, released in Nov, 2019. If your project needs to support build from sdist on older versions of Setuptools, you will need to also implement the setup.py usage for those legacy environments.

First, ensure that setuptools_scm is present during the project’s built step by specifying it as one of the build requirements.

# pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2"]

That will be sufficient to require setuptools_scm for projects that support PEP 518 (pip and pep517). Many tools, especially those that invoke setup.py for any reason, may continue to rely on setup_requires. For maximum compatibility with those uses, consider also including a setup_requires directive (described below in setup.py usage and setup.cfg).

To enable version inference, add this section to your pyproject.toml:

# pyproject.toml
[tool.setuptools_scm]

Including this section is comparable to supplying use_scm_version=True in setup.py. Additionally, include arbitrary keyword arguments in that section to be supplied to get_version(). For example:

# pyproject.toml

[tool.setuptools_scm]
write_to = "pkg/_version.py"

setup.py usage (deprecated)

The following settings are considered legacy behavior and superseded by the pyproject.toml usage, but for maximal compatibility, projects may also supply the configuration in this older form.

To use setuptools_scm just modify your project’s setup.py file like this:

• Add setuptools_scm to the setup_requires parameter.

• Add the use_scm_version parameter and set it to True.

For example:

from setuptools import setup
setup(
    ...,
    use_scm_version=True,
    setup_requires=['setuptools_scm'],
    ...,
)

Arguments to get_version() (see below) may be passed as a dictionary to use_scm_version. For example:

from setuptools import setup
setup(
    ...,
    use_scm_version = {
        "root": "..",
        "relative_to": __file__,
        "local_scheme": "node-and-timestamp"
    },
    setup_requires=['setuptools_scm'],
    ...,
)

You can confirm the version number locally via setup.py:

$ python setup.py --version

setup.cfg usage (deprecated)

as setup_requires is deprecated in favour of pyproject.toml usage in setup.cfg is considered deprecated, please use pyproject.toml whenever possible.

Programmatic usage

In order to use setuptools_scm from code that is one directory deeper than the project’s root, you can use:

from setuptools_scm import get_version
version = get_version(root='..', relative_to=__file__)

See setup.py Usage (deprecated) above for how to use this within setup.py.

Retrieving package version at runtime

If you have opted not to hardcode the version number inside the package, you can retrieve it at runtime from PEP-0566 metadata using importlib.metadata from the standard library (added in Python 3.8) or the importlib_metadata backport:

from importlib.metadata import version, PackageNotFoundError

try:
    __version__ = version("package-name")
except PackageNotFoundError:
    # package is not installed
    pass

Alternatively, you can use pkg_resources which is included in setuptools (but has a significant runtime cost):

from pkg_resources import get_distribution, DistributionNotFound

try:
    __version__ = get_distribution("package-name").version
except DistributionNotFound:
     # package is not installed
    pass

However, this does place a runtime dependency on setuptools and can add up to a few 100ms overhead for the package import time.

Usage from Sphinx

It is discouraged to use setuptools_scm from Sphinx itself, instead use importlib.metadata after editable/real installation:

# contents of docs/conf.py
from importlib.metadata import version
release = version('myproject')
# for example take major/minor
version = '.'.join(release.split('.')[:2])

The underlying reason is, that services like Read the Docs sometimes change the working directory for good reasons and using the installed metadata prevents using needless volatile data there.

Usage from Docker

By default, docker will not copy the .git folder into your container. Therefore, builds with version inference might fail. Consequently, you can use the following snipped to infer the version from the host os without copying the entire .git folder to your Dockerfile.

RUN --mount=source=.git,target=.git,type=bind \
    pip install --no-cache-dir -e .

However, this build step introduces a dependency to the state of your local .git folder the build cache and triggers the long-running pip install process on every build. To optimize build caching, one can use an environment variable to pretend a pseudo version that is used to cache the results of the pip install process:

FROM python
COPY pyproject.toml
ARG PSEUDO_VERSION=1
RUN SETUPTOOLS_SCM_PRETEND_VERSION=${PSEUDO_VERSION} pip install -e .[test]
RUN --mount=source=.git,target=.git,type=bind pip install -e .

Note that running this Dockerfile requires docker with BuildKit enabled [docs].

To avoid BuildKit and mounting of the .git folder altogether, one can also pass the desired version as a build argument. Note that SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${UPPERCASED_DIST_NAME} is preferred over SETUPTOOLS_SCM_PRETEND_VERSION.

Notable Plugins

setuptools_scm_git_archive

Provides partial support for obtaining versions from git archives that belong to tagged versions. The only reason for not including it in setuptools_scm itself is Git/GitHub not supporting sufficient metadata for untagged/followup commits, which is preventing a consistent UX.

Default versioning scheme

In the standard configuration setuptools_scm takes a look at three things:

1. latest tag (with a version number)

2. the distance to this tag (e.g. number of revisions since latest tag)

3. workdir state (e.g. uncommitted changes since latest tag)

and uses roughly the following logic to render the version:

no distance and clean:

{tag}

distance and clean:

{next_version}.dev{distance}+{scm letter}{revision hash}

no distance and not clean:

{tag}+dYYYYMMDD

distance and not clean:

{next_version}.dev{distance}+{scm letter}{revision hash}.dYYYYMMDD

The next version is calculated by adding 1 to the last numeric component of the tag.

For Git projects, the version relies on git describe, so you will see an additional g prepended to the {revision hash}.

Builtin mechanisms for obtaining version numbers

1. the SCM itself (git/hg)

2. .hg_archival files (mercurial archives)

3. PKG-INFO

File finders hook makes most of MANIFEST.in unnecessary

setuptools_scm implements a file_finders entry point which returns all files tracked by your SCM. This eliminates the need for a manually constructed MANIFEST.in in most cases where this would be required when not using setuptools_scm, namely:

• To ensure all relevant files are packaged when running the sdist command.

• When using include_package_data to include package data as part of the build or bdist_wheel.

MANIFEST.in may still be used: anything defined there overrides the hook. This is mostly useful to exclude files tracked in your SCM from packages, although in principle it can be used to explicitly include non-tracked files too.

Configuration parameters

In order to configure the way use_scm_version works you can provide a mapping with options instead of a boolean value.

The currently supported configuration keys are:

root:

Relative path to cwd, used for finding the SCM root; defaults to .

version_scheme:

Configures how the local version number is constructed; either an entrypoint name or a callable.

local_scheme:

Configures how the local component of the version is constructed; either an entrypoint name or a callable.

write_to:

A path to a file that gets replaced with a file containing the current version. It is ideal for creating a _version.py file within the package, typically used to avoid using pkg_resources.get_distribution (which adds some overhead).

write_to_template:

A newstyle format string that is given the current version as the version keyword argument for formatting.

relative_to:

A file from which the root can be resolved. Typically called by a script or module that is not in the root of the repository to point setuptools_scm at the root of the repository by supplying __file__.

tag_regex:

A Python regex string to extract the version part from any SCM tag.

The regex needs to contain either a single match group, or a group named version, that captures the actual version information.

Defaults to the value of setuptools_scm.config.DEFAULT_TAG_REGEX (see config.py).

parentdir_prefix_version:

If the normal methods for detecting the version (SCM version, sdist metadata) fail, and the parent directory name starts with parentdir_prefix_version, then this prefix is stripped and the rest of the parent directory name is matched with tag_regex to get a version string. If this parameter is unset (the default), then this fallback is not used.

This is intended to cover GitHub’s “release tarballs”, which extract into directories named projectname-tag/ (in which case parentdir_prefix_version can be set e.g. to projectname-).

fallback_version:

A version string that will be used if no other method for detecting the version worked (e.g., when using a tarball with no metadata). If this is unset (the default), setuptools_scm will error if it fails to detect the version.

parse:

A function that will be used instead of the discovered SCM for parsing the version. Use with caution, this is a function for advanced use, and you should be familiar with the setuptools_scm internals to use it.

git_describe_command:

This command will be used instead the default git describe command. Use with caution, this is a function for advanced use, and you should be familiar with the setuptools_scm internals to use it.

Defaults to the value set by setuptools_scm.git.DEFAULT_DESCRIBE (see git.py).

normalize:

A boolean flag indicating if the version string should be normalized. Defaults to True. Setting this to False is equivalent to setting version_cls to setuptools_scm.version.NonNormalizedVersion

version_cls:

An optional class used to parse, verify and possibly normalize the version string. Its constructor should receive a single string argument, and its str should return the normalized version string to use. This option can also receive a class qualified name as a string.

This defaults to packaging.version.Version if available. If packaging is not installed, pkg_resources.packaging.version.Version is used. Note that it is known to modify git release candidate schemes.

The setuptools_scm.NonNormalizedVersion convenience class is provided to disable the normalization step done by packaging.version.Version. If this is used while setuptools_scm is integrated in a setuptools packaging process, the non-normalized version number will appear in all files (see write_to) BUT note that setuptools will still normalize it to create the final distribution, so as to stay compliant with the python packaging standards.

To use setuptools_scm in other Python code you can use the get_version function:

from setuptools_scm import get_version
my_version = get_version()

It optionally accepts the keys of the use_scm_version parameter as keyword arguments.

Example configuration in setup.py format:

from setuptools import setup

setup(
    use_scm_version={
        'write_to': '_version.py',
        'write_to_template': '__version__ = "{version}"',
        'tag_regex': r'^(?P<prefix>v)?(?P<version>[^\+]+)(?P<suffix>.*)?$',
    }
)

Environment variables

SETUPTOOLS_SCM_PRETEND_VERSION:

when defined and not empty, its used as the primary source for the version number in which case it will be a unparsed string

SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${UPPERCASED_DIST_NAME}:

when defined and not empty, its used as the primary source for the version number in which case it will be a unparsed string

it takes precedence over SETUPTOOLS_SCM_PRETEND_VERSION

SETUPTOOLS_SCM_DEBUG:

when defined and not empty, a lot of debug information will be printed as part of setuptools_scm operating

SOURCE_DATE_EPOCH:

when defined, used as the timestamp from which the node-and-date and node-and-timestamp local parts are derived, otherwise the current time is used (https://reproducible-builds.org/docs/source-date-epoch/)

SETUPTOOLS_SCM_IGNORE_VCS_ROOTS:

when defined, a os.pathsep separated list of directory names to ignore for root finding

Extending setuptools_scm

setuptools_scm ships with a few setuptools entrypoints based hooks to extend its default capabilities.

# content of setup.py
import setuptools

def myversion():
    from setuptools_scm.version import get_local_dirty_tag
    def clean_scheme(version):
        return get_local_dirty_tag(version) if version.dirty else '+clean'

    return {'local_scheme': clean_scheme}

setup(
    ...,
    use_scm_version=myversion,
    ...
)

$ python setup.py egg_info
$ PYTHONPATH=$PWD:$PWD/src pytest

Code of Conduct

Everyone interacting in the setuptools_scm project’s codebases, issue trackers, chat rooms, and mailing lists is expected to follow the PSF Code of Conduct.