Python Bumpversion Release — Core Concepts

What Bumpversion Does

bump-my-version (the maintained successor to the original bumpversion and bump2version) is a tool that increments version strings across multiple files in a project, creates Git commits, and tags releases. It enforces consistent versioning without manual edits.

Install it:

pip install bump-my-version

Configuration

Add to pyproject.toml:

[tool.bumpversion]
current_version = "1.3.2"
commit = true
tag = true
tag_name = "v{new_version}"
tag_message = "Release {new_version}"

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

[[tool.bumpversion.files]]
filename = "src/mypackage/__init__.py"
search = '__version__ = "{current_version}"'
replace = '__version__ = "{new_version}"'

[[tool.bumpversion.files]]
filename = "docs/conf.py"
search = 'release = "{current_version}"'
replace = 'release = "{new_version}"'

Bumping Versions

Semantic versioning has three parts: MAJOR.MINOR.PATCH (e.g., 1.3.2).

bump-my-version bump patch   # 1.3.2 → 1.3.3
bump-my-version bump minor   # 1.3.2 → 1.4.0
bump-my-version bump major   # 1.3.2 → 2.0.0

Each command:

1. Reads the current version from config
2. Calculates the new version
3. Replaces the old version string in all configured files
4. Creates a Git commit with the changes
5. Creates a Git tag (e.g., v1.4.0)

Pre-Release Versions

For alpha/beta/rc workflows:

[tool.bumpversion]
current_version = "2.0.0"
parse = '(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\.(?P<pre>alpha|beta|rc)(?P<pre_n>\d+))?'
serialize = [
    "{major}.{minor}.{patch}.{pre}{pre_n}",
    "{major}.{minor}.{patch}"
]

bump-my-version bump pre_n --new-version 2.0.0.alpha1
bump-my-version bump pre_n   # 2.0.0.alpha1 → 2.0.0.alpha2
bump-my-version bump pre     # 2.0.0.alpha2 → 2.0.0.beta1
bump-my-version bump patch   # 2.0.0.beta1 → 2.0.0

Dry Run

Preview what would change without modifying anything:

bump-my-version bump minor --dry-run --verbose

This shows every file that would be modified and the exact search/replace operations.

How It Differs from Commitizen

Aspect	bump-my-version	Commitizen
Version source	Config file (you decide)	Commit history (computed)
Commit format	No opinion	Enforces Conventional Commits
Changelog	Not included	Built-in
Flexibility	Any versioning scheme	Tied to commit types

bump-my-version is version-centric: “I want to bump to this version.” Commitizen is commit-centric: “my commits determine the version.” Teams that want full control over when and how they version prefer bump-my-version. Teams that want automated, commit-driven releases prefer Commitizen.

Common Misconception

“Bumpversion is abandoned.” The original bumpversion is unmaintained, and bump2version was a fork that also slowed down. But bump-my-version is actively maintained with Python 3.12+ support, pyproject.toml integration, and regular releases. Always install bump-my-version, not the older packages.

One thing to remember: bump-my-version gives you a reliable, repeatable “release button” — one command updates every version string, commits, and tags, so releases are never a manual scramble.