Check whether a version string is PEP 440 compliant and optionally compare it with a version declared in a TOML manifest or a Python module's __version__ attribute.

• Python 3.11+
• No runtime dependencies outside the standard library

Install the CLI with uv:

uv tool install vercheck

Or run it directly without installing:

uvx vercheck --help

Use Vercheck in CI to validate release tags or package versions before publishing:

jobs:
  release-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@
      - name: Version must match tag name
        if: >-
          github.event_name == 'push' &&
          startsWith(github.ref, 'refs/tags')
        run: uvx vercheck "$GITHUB_REF_NAME" --py=src/mypkg/about.py

For TOML-based checks:

jobs:
  release-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
      - run: uvx vercheck "$GITHUB_REF_NAME" --toml=pyproject.toml

Vercheck works as a pre-commit/prek hook.

repos:
  - repo: https://github.com/cleder/vercheck
    rev: v0.4.0
    hooks:
      - id: vercheck
      - id: vercheck-py
        args: [--py=src/mypkg/about.py]

uvx vercheck 0.2.0
uvx vercheck 0.2.0 --toml
uvx vercheck 0.2.0 --py=src/mypkg/about.py

Use --toml to compare against a TOML manifest, --py to compare against a module's __version__ attribute, and omit the version argument to validate the declared version in place.

You can pass multiple --toml entries when you want to validate more than one manifest at once. All resolved versions must agree, which is useful for Maturin-style setups that keep the version in both pyproject.toml and Cargo.toml.

If the version is not under the built-in project.version (for pyproject.toml) or package.version (Cargo.toml) default, pass an explicit TOML key path.

uvx vercheck 0.2.0 --toml=pyproject.toml:tool.poetry.version
uvx vercheck 0.2.0 --toml=some.toml:custom.nested.key

Put the version argument before --toml or --py.

Version strings are easy to get wrong. Vercheck helps you confirm that:

• a release tag matches a valid PEP 440 version string;
• a package version in a manifest matches the version you intend to ship; and
• a module-level __version__ stays consistent with your release.

Contributions are very welcome. To learn more, see the Contributor Guide.

Distributed under the terms of the MIT license.

If you encounter any problems, please file an issue along with a detailed description.

dynamic-versioning