Configuration Reference¶

bumpwright reads settings from bumpwright.toml. Missing sections fall back to built-in defaults. Use --config to point to an alternative file.

Note

Environment variables prefixed with BUMPWRIGHT_ provide default values for CLI flags. See Environment variables for the full list.

Configuration overview¶

A bumpwright.toml file is divided into thematic sections that mirror the tool’s major features. Each section groups related options controlling project scope, analysis behaviour, or release outputs. The table below provides a quick map before diving into the detailed references.

Configuration sections¶
Section	Purpose	Category
Project	Define the package roots and visibility rules.	Project
Ignore	Exclude paths from analysis.	Project
Rules	Override default bump levels for API changes.	Project
Analysers	Enable and configure API analysers.	Analysis
Migrations	Locate Alembic migration directories.	Analysis
OpenAPI	Configure OpenAPI specification paths.	Analysis
Version	Control version file detection and scheme.	Output
Changelog	Configure changelog generation.	Output

Quick setup¶

Create bumpwright.toml in the project root and enable any analysers you need:

[project]
package = "my_package"

[analysers]
cli = true

Run bumpwright bump --base v1.0.0 --head HEAD to compare revisions. See quickstart for a walkthrough.

Console

bumpwright bump --base v1.0.0 --head HEAD

Output

bumpwright suggests: minor

Reference¶

All configuration keys are grouped by section below. Each block shows default values and accepted types.

Project¶

[project]
package = ""
public_roots = ["."]
private_prefixes = ["_"]
extra_public_files = ["README.*", "docs/**/*.rst"]

Key	Default	CLI flag
`package`	`""`	(none)
`public_roots`	`["."]`	(none)
`private_prefixes`	`["_"]`	(none)
`extra_public_files`	`["README.", "docs//.rst"]`	(none)

package: Importable package containing the project’s code. When empty the repository layout is used.
public_roots: Paths whose contents constitute the public API. Any modified Python file within these roots triggers a patch bump, even if only private helpers change.
private_prefixes: Symbol prefixes treated as private and ignored during API analysis.
extra_public_files: Additional glob patterns for files that trigger a patch bump when modified.

Ignore¶

[ignore]
paths = ["tests/**", "examples/**", "scripts/**"]

Key	Default	CLI flag
`paths`	`["tests/", "examples/", "scripts/**"]`	(none)

paths: Glob patterns excluded from analysis.

Rules¶

bumpwright detects common public API changes and assigns default semantic version bumps:

Added public symbol: minor
Removed public symbol: major
Added required parameter: major
Added optional parameter: minor
Removed required parameter: major
Removed optional parameter: minor
Parameter kind changed: major
Parameter default added or changed: minor
Parameter default removed: major
Return type changed: minor *
Parameter annotation changed: patch *
Implementation changed: patch *

Entries marked with * can be overridden in bumpwright.toml via the [rules] section:

[rules]
return_type_change = "major"
param_annotation_change = "minor"
implementation_change = "minor"

Key	Default	CLI flag
`return_type_change`	`"minor"`	(none)
`param_annotation_change`	`"patch"`	(none)
`implementation_change`	`"patch"`	(none)

return_type_change: Bump level when a function’s return type changes.

param_annotation_change: Bump level for parameter annotation changes.

implementation_change: Bump level when a public symbol’s implementation changes without altering its signature.

Examples¶

Removing a public symbol triggers a major bump:

Before

def add(a: int, b: int) -> int:
    return a + b

After

# ``add`` removed

Changing a return type triggers a minor bump by default:

Before

def greet() -> str:
    return "hi"

After

def greet() -> int:
    return 1

Analysers¶

[analysers]
cli = false
grpc = false
web_routes = false
migrations = false
openapi = false
graphql = false

Key	Default	CLI flag
`cli`	`false`	`--enable-analyser cli`
`grpc`	`false`	`--enable-analyser grpc`
`web_routes`	`false`	`--enable-analyser web_routes`
`migrations`	`false`	`--enable-analyser migrations`
`openapi`	`false`	`--enable-analyser openapi`
`graphql`	`false`	`--enable-analyser graphql`

cli: Detects changes to command-line interfaces implemented with argparse or click.
grpc: Detects gRPC service and method changes in .proto files.
web_routes: Tracks additions or removals of web routes in frameworks such as Flask or FastAPI.
migrations: Scans Alembic migrations for schema impacts.
openapi: Detects changes to OpenAPI specification files.
graphql: Detects GraphQL schema changes.

Migrations¶

[migrations]
paths = ["migrations"]

paths: Default: ["migrations"] Directories containing Alembic migration scripts to inspect.

OpenAPI¶

[openapi]
paths = ["openapi.yaml", "openapi.yml", "openapi.json"]

paths: Default: ["openapi.yaml", "openapi.yml", "openapi.json"] Paths to OpenAPI specification documents.

Version¶

[version]
paths = [
    "pyproject.toml",
    "setup.py",
    "setup.cfg",
    "**/__init__.py",
    "**/version.py",
    "**/_version.py",
]
ignore = [
    "build/**",
    "dist/**",
    "*.egg-info/**",
    ".eggs/**",
    ".venv/**",
    "venv/**",
    ".env/**",
    "**/__pycache__/**",
]
scheme = "semver"

Key	Default	CLI flag
`paths`	`["pyproject.toml", "setup.py", "setup.cfg", "/__init__.py", "/version.py", "**/_version.py"]`	`--version-path`
`ignore`	`["build/", "dist/", ".egg-info/", ".eggs/", ".venv/", "venv/", ".env/", "/__pycache__/*"]`	`--version-ignore`
`scheme`	`"semver"`	(none)

paths: Glob patterns scanned for version declarations.
ignore: Glob patterns appended to the default exclusion list for version replacement.
scheme: Versioning scheme used when bumping. Supported values include "semver" and "calver".

Changelog¶

[changelog]
path = ""
template = ""
exclude = []
repo_url = ""

Key	Default	CLI flag
`path`	`""`	`--changelog`
`template`	`""`	`--changelog-template`
`exclude`	`[]`	`--changelog-exclude`
`repo_url`	`""`	`--repo-url`

path: Changelog file location. Empty string disables generation.
template: Jinja2 template file. Empty string uses the built-in template.
exclude: Regular expressions for commit subjects to omit.
repo_url: Base repository URL for commit and compare links.

Examples¶

Custom version rules¶

[rules]
return_type_change = "major"

Ignore paths¶

[ignore]
paths = ["tests/**", "examples/**"]

Version file locations¶

[version]
paths = ["pyproject.toml", "setup.py", "src/pkg/__init__.py"]
ignore = ["examples/**"]
scheme = "semver"

Automatic bump with commit and tag¶

For a walkthrough that commits and tags the new version automatically, see guides/version-management/automatic-bump-commit-tag.

Environment variables¶

bumpwright reads defaults for many CLI flags from environment variables.

Variable	Default	CLI flag	Used by
`BUMPWRIGHT_CONFIG`	`bumpwright.toml`	`--config`	all
`BUMPWRIGHT_QUIET`	`False`	`--quiet`	all
`BUMPWRIGHT_VERBOSE`	`False`	`--verbose`	all
`BUMPWRIGHT_SUMMARY`	`None`	`--summary`	init
`BUMPWRIGHT_BASE`	last release or `HEAD^`	`--base`	decide, bump
`BUMPWRIGHT_HEAD`	`HEAD`	`--head`	decide, bump
`BUMPWRIGHT_FORMAT`	`text`	`--format`	decide, bump, history
`BUMPWRIGHT_REPO_URL`	`None`	`--repo-url`	decide, bump
`BUMPWRIGHT_EXPLAIN`	`False`	`--explain`	decide, bump
`BUMPWRIGHT_ENABLE_ANALYSER`	`-`	`--enable-analyser`	decide, bump
`BUMPWRIGHT_DISABLE_ANALYSER`	`-`	`--disable-analyser`	decide, bump
`BUMPWRIGHT_PYPROJECT`	`pyproject.toml`	`--pyproject`	bump
`BUMPWRIGHT_VERSION_PATH`	`-`	`--version-path`	bump
`BUMPWRIGHT_VERSION_IGNORE`	`-`	`--version-ignore`	bump
`BUMPWRIGHT_TAG`	`False`	`--tag`	bump
`BUMPWRIGHT_DRY_RUN`	`False`	`--dry-run`	bump
`BUMPWRIGHT_CHANGELOG`	`None`	`--changelog`	bump
`BUMPWRIGHT_CHANGELOG_TEMPLATE`	`None`	`--changelog-template`	decide, bump
`BUMPWRIGHT_CHANGELOG_EXCLUDE`	`-`	`--changelog-exclude`	decide, bump
`BUMPWRIGHT_STATS`	`False`	`--stats`	history
`BUMPWRIGHT_ROLLBACK`	`None`	`--rollback`	history
`BUMPWRIGHT_PURGE`	`False`	`--purge`	history

BUMPWRIGHT_CONFIG: Path to configuration file.
BUMPWRIGHT_QUIET: Only display warnings and errors.
BUMPWRIGHT_VERBOSE: Show debug messages.
BUMPWRIGHT_SUMMARY: Show project summary after initialisation.
BUMPWRIGHT_BASE: Base git reference when auto-deciding the level.
BUMPWRIGHT_HEAD: Head git reference.
BUMPWRIGHT_FORMAT: Output style for CLI commands.
BUMPWRIGHT_REPO_URL: Base repository URL for linking commit hashes in Markdown output.
BUMPWRIGHT_EXPLAIN: Show reasoning behind the selected bump level.
BUMPWRIGHT_ENABLE_ANALYSER: Enable analyser names in addition to configuration.
BUMPWRIGHT_DISABLE_ANALYSER: Disable analyser names even if configured.
BUMPWRIGHT_PYPROJECT: Path to the project’s pyproject.toml file.
BUMPWRIGHT_VERSION_PATH: Additional glob pattern for files containing the project version.
BUMPWRIGHT_VERSION_IGNORE: Glob pattern for files to exclude from version updates.
BUMPWRIGHT_TAG: Create a git tag for the new version.
BUMPWRIGHT_DRY_RUN: Display the new version without modifying any files.
BUMPWRIGHT_CHANGELOG: Append release notes to a file or stdout when set to -.
BUMPWRIGHT_CHANGELOG_TEMPLATE: Jinja2 template file for changelog entries.
BUMPWRIGHT_CHANGELOG_EXCLUDE: Regex pattern for commit subjects to exclude from the changelog.
BUMPWRIGHT_STATS: Include line change statistics between successive tags.
BUMPWRIGHT_ROLLBACK: Delete a tag and restore files to the previous commit.
BUMPWRIGHT_PURGE: Remove all bumpwright release tags and commits.

CLI equivalents¶

Many configuration keys have corresponding command-line flags. For a complete mapping, see the cli_reference.