Bump My Version

1.3.0 · active · verified Sun Apr 12

Bump My Version is a command-line tool designed to simplify software releases by automatically updating version strings across project files, optionally committing changes, and creating Git tags. It is a maintained refactor of the `bump2version` fork of `bumpversion`, offering enhanced features like `pyproject.toml` configuration support, a modern CLI built with `click` and `rich`, and robust configuration validation using `Pydantic`. It supports various versioning schemes including Semantic Versioning (SemVer) and Calendar Versioning (CalVer). The current version is 1.3.0, and it has an active development and release cadence.

Warnings

breaking The command-line invocation changed significantly in version 0.6.0, splitting functionality into sub-commands (e.g., `bump-my-version bump <part>`). While older syntax might still be backward-compatible for now, it is discouraged and may be removed in a future 1.0 release.
Fix: Update your scripts to use the new sub-command syntax, e.g., `bump-my-version bump minor` instead of `bump-my-version minor`.
gotcha Unlike its predecessor `bump2version`, `bump-my-version` may silently succeed even if it fails to find and modify all configured files, potentially leading to desynchronized version strings across your project. Ensure your configuration's `search` and `replace` patterns accurately match your files.
Fix: Always verify file changes after a bump, especially in automated workflows. Review your `.bumpversion.toml` or `pyproject.toml` `files` and `search` configurations carefully to ensure they match expected version strings.
deprecated The `--list` command-line option is deprecated.
Fix: Use `bump-my-version show` instead to get machine-readable output.
gotcha As of March 22, 2026, the `allow_shell_hooks` configuration is now `false` by default, disallowing shell metacharacters in hooks unless explicitly enabled. This is a security-related change.
Fix: If your workflow relies on shell metacharacters in hooks, you must explicitly set `allow_shell_hooks = true` in your configuration file.
gotcha Configuration files are resolved in a specific order: `--config-file`, `BUMPVERSION_CONFIG_FILE` environment variable, `.bumpversion.cfg` (legacy), `.bumpversion.toml`, `setup.cfg` (legacy), `pyproject.toml`. Conflicting settings might lead to unexpected behavior if files are not ordered correctly or legacy configs are present.
Fix: Prefer using `pyproject.toml` or `.bumpversion.toml` for modern configurations and remove older `.bumpversion.cfg` or `setup.cfg` files to avoid ambiguity. Always explicitly specify your configuration file if there's any doubt.

Install

pip install bump-my-version Install via pip

Quickstart

This quickstart demonstrates how to set up `bump-my-version` for a new project and perform a basic version bump. It starts by creating a dummy project and then initializes a `.bumpversion.toml` configuration file. Finally, it uses the `bump` subcommand to increment the 'minor' version component, updating both the source file and the configuration itself. By default, it will look for version strings defined in `pyproject.toml` or `__init__.py` files based on the generated config.

# 1. Create a sample project structure and initialize a git repo
mkdir my-project
cd my-project
git init
echo '__version__ = "0.1.0"' > my_project/__init__.py
mkdir my_project

# 2. Generate a default configuration file (e.g., .bumpversion.toml)
bump-my-version sample-config --no-prompt --destination .bumpversion.toml

# 3. Inspect the generated config (optional)
cat .bumpversion.toml

# 4. Bump the 'minor' version (will update __init__.py and .bumpversion.toml)
bump-my-version bump minor

# 5. Verify the version has been bumped
cat my_project/__init__.py
cat .bumpversion.toml

# You can also bump other parts like 'major' or 'patch'
# bump-my-version bump major

view raw JSON →