How to Catch Python Package Version Drift Before You Ship

You published 1.2.3 to PyPI. Your git tag says 1.2.0. And the __version__ string in your package is still 0.9.0 from last year. None of your users will notice — until they pip install the "new" release and get the old code, or a downstream tool pins the wrong version and your changelog lies to them.

This is version drift, and it's one of the most common silent failures in Python packaging. The worst part: pytest passes, build succeeds, and CI is green. Nothing catches it.

Where drift hides

A modern Python package can declare its version in three places, and they drift independently:

• pyproject.toml → [project].version (what PyPI shows)
• src/<pkg>/__init__.py → __version__ (what importlib.metadata returns at runtime)
• your git tag v1.2.3 (what your release tool reads)

Each is edited by a different command, often by a different person, usually at 11pm before a release. Miss one and you've shipped a lie.

The manual check (don't do this forever)

# pyproject
grep version pyproject.toml
# init
grep __version__ src/mypkg/__init__.py
# git
git describe --tags --abbrev=0

If those three don't match, stop and fix it. But this is exactly the kind of check people "forget" to run — which is why it belongs in CI.

Automate it: fail the build on drift

The cleanest approach is a metadata scanner that runs as a CI gate and exits non-zero on any mismatch. That's the entire job of kryptorious-metaguard:

pip install kryptorious-metaguard
metaguard check .

It compares all three version sources, plus catches a stack of related issues:

• Stale CHANGELOG.md (top entry doesn't match the declared version)
• Missing PEP 621 fields (description, authors, license, requires-python)
• license declared in pyproject but no LICENSE file at root
• Committed secret files (.env, *.pem, *.key, .pypirc) — respects .gitignore
• Optionally: dead README links

Wire it into GitHub Actions and a single drifted version fails the pipeline instead of reaching PyPI:

- name: Metadata hygiene
  run: metaguard check .

Stop drift at the source

Even better than detecting drift: generating it. DevFlow's ship command bumps the version, updates the changelog, and tags git in one step — so all three sources move together. Pair it with MetaGuard as a guard rail and version drift becomes a non-event.

Tools mentioned: kryptorious-metaguard · kryptorious-devflow. Part of the Kryptorious developer toolkit.

← Back to Blog · ← Kryptorious Tools

← All posts