Bumping Versions Consistently Across a Python CLI Project

The version number of a CLI shows up in more places than anyone remembers: pyproject.toml, the lock file, a __version__ constant someone added years ago, the changelog heading, a Homebrew formula, a Dockerfile label, the docs' installation snippet, perhaps a man page. Releases go wrong when these disagree — mytool --version says 1.5.2 while PyPI has 1.6.0, the formula still downloads last month's tarball, the changelog's newest heading is two releases old. This guide reduces the number of places a version is written by hand to one, automates the rest with bump-my-version, and adds a test that fails the build when anything drifts. It belongs to the versioning and changelogs topic.

Prerequisites

• A CLI project with a pyproject.toml; uv for the commands shown (other tools work the same way).
• bump-my-version, run with uvx bump-my-version so it needs no project dependency.
• Git, since the bump commits and tags.

Fewer copies first

The best way to keep copies in sync is to not have them. Before automating anything, remove every copy that can be derived:

• Inside the package, read the installed metadata rather than storing a constant: importlib.metadata.version("mytool") always matches what is installed. Exposing version info and build metadata covers the details, including the fallback for running from a source checkout.
• Let the lock file follow pyproject.toml. uv lock updates the project's own entry; nobody should edit uv.lock by hand.
• Generate documentation snippets from the version at build time instead of hard-coding "pip install mytool==1.5.2".
• Or derive everything from git tags. With hatch-vcs or setuptools-scm, the tag is the only place a version is written, and the build fills in the rest — see deriving versions from git tags with hatch-vcs.

What remains are files that must contain a literal version and that you do not want to template: the changelog, a Homebrew formula or Scoop manifest kept in the repository, perhaps a CITATION.cff. Those are what a bump tool is for.

Finding every copy

Before deciding what to automate, find out where the current version actually appears. A quick search for the literal string usually turns up surprises:

git grep -n --fixed-strings "1.5.2" -- ':!uv.lock' ':!CHANGELOG.md'

Typical results in a CLI repository, and what to do with each:

Excluding the lock file and changelog keeps the output focused — those are expected to contain versions. Anything else that matches is either a copy to remove, a file for the bump tool, or a coincidence (a dependency that happens to share the number) that confirms why precise search patterns matter. Re-run the search occasionally; new copies creep in with new files.

The recipe

Simple case: uv version

If pyproject.toml is the only file with a literal version, uv does the whole job:

uv version --bump minor         # pyproject.toml and uv.lock, together

Several files: bump-my-version

bump-my-version (the maintained successor to bumpversion and bump2version) reads its configuration from pyproject.toml, rewrites every listed file, and optionally commits and tags:

[tool.bumpversion]
current_version = "1.5.2"
commit = true
tag = true
tag_name = "v{new_version}"
message = "Release {new_version}"
pre_commit_hooks = ["uv lock", "git add uv.lock"]

[[tool.bumpversion.files]]
filename = "pyproject.toml"
search = 'version = "{current_version}"'
replace = 'version = "{new_version}"'

[[tool.bumpversion.files]]
filename = "CHANGELOG.md"
search = "## [Unreleased]"
replace = "## [Unreleased]\n\n## [{new_version}] - {now:%Y-%m-%d}"

[[tool.bumpversion.files]]
filename = "packaging/homebrew/mytool.rb"
search = 'version "{current_version}"'
replace = 'version "{new_version}"'

Each [[tool.bumpversion.files]] entry names a file and the exact text to find and replace. Searching for version = "1.5.2" rather than the bare 1.5.2 matters: the bare number might also appear as a dependency pin, a date or an unrelated example, and a bump tool that replaces all of them silently corrupts files. The changelog entry turns the Unreleased heading into a dated release heading and opens a fresh Unreleased section above it, which is the Keep a Changelog convention. The pre_commit_hooks run after the files are rewritten and before the commit, so uv.lock is updated and included in the same commit.

uvx bump-my-version show-bump          # preview the possible next versions
uvx bump-my-version bump minor --dry-run -v
uvx bump-my-version bump minor         # rewrite, re-lock, commit, tag
git push --follow-tags                 # CI publishes from the tag

The result is one commit that changes every version-bearing file at once, and a tag pointing at it. Because CI publishes from the tag, the published artefacts and the repository can never disagree about which commit is 1.6.0.

Pre-releases

bump-my-version's default version pattern is major.minor.patch. To bump into and out of release candidates, extend the parse and serialise patterns, or use uv version --bump rc for pyproject.toml and let bump-my-version handle only the files that should change for final releases. Shipping pre-releases and release candidates describes the cycle; most projects only update the Homebrew formula and changelog heading for final releases anyway.

UX considerations

The users of this process are maintainers who release a few times a month at most and forget the steps in between:

• One command. bump-my-version bump minor or a just release minor wrapper. Anything that needs a checklist will eventually be done wrong.
• Refuse a dirty tree. bump-my-version does this by default when committing; keep it that way, so a release never includes unrelated edits.
• Preview before writing. --dry-run -v prints every replacement it would make — the fastest way to debug a search pattern that does not match.
• Fail when a pattern is missing. By default bump-my-version errors if a configured search string is not found in a file; do not turn that off, because it is how you learn that someone reformatted the Homebrew formula.
• Keep current_version honest. It is the tool's only memory. If someone bumps by hand, the next automated bump fails to find its patterns, which is the right outcome — fix the config rather than forcing it.

Testing the behaviour

A consistency test turns "the versions agree" into something CI checks on every commit, independent of how the bump was done:

# tests/test_version_consistency.py
import re
import tomllib
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]


def project_version() -> str:
    return tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]["version"]


def test_bumpversion_config_matches_project():
    data = tomllib.loads((ROOT / "pyproject.toml").read_text())
    assert data["tool"]["bumpversion"]["current_version"] == project_version()


def test_lock_file_matches_project():
    lock = tomllib.loads((ROOT / "uv.lock").read_text())
    entry = next(p for p in lock["package"] if p["name"] == "mytool")
    assert entry["version"] == project_version()


def test_changelog_has_heading_for_current_version():
    text = (ROOT / "CHANGELOG.md").read_text()
    assert re.search(rf"^## \[{re.escape(project_version())}\]", text, re.M), \
        "CHANGELOG.md has no heading for the current version"


def test_homebrew_formula_matches_project():
    formula = (ROOT / "packaging/homebrew/mytool.rb").read_text()
    assert f'version "{project_version()}"' in formula

During development between releases, the changelog test fails if the newest heading is still [Unreleased] and the version was bumped without a release — which is precisely the inconsistency you want to know about. Add one more check to the built-wheel smoke test: that mytool --version prints the same number.

Conclusion

Version drift is a symptom of too many hand-maintained copies. Remove the ones you can derive — read installed metadata in code, let uv lock follow pyproject.toml, generate docs snippets — then let uv version or bump-my-version rewrite the rest in one commit with a tag, using precise search patterns and a pre-commit hook for the lock file. A small consistency test makes sure that whichever way a bump happens, CI notices when the numbers disagree.

Frequently asked questions

Related

• Up: Managing CLI versioning and changelogs
• Shipping pre-releases and release candidates
• Exposing version info and build metadata
• Building and publishing a CLI with uv
• Homebrew and Scoop packaging for Python CLIs