Version Providers¶

Version providers are the mechanism by which Commitizen reads and writes version information in your project.

They abstract away the details of where and how version numbers are stored, allowing Commitizen to work seamlessly with different project types and package management systems.

Overview¶

By default, Commitizen uses the commitizen provider, which stores the version in your Commitizen configuration file. However, you can configure Commitizen to use any available provider that matches your project's setup. This is particularly useful when you want Commitizen to manage versions in the same location as your package manager (e.g., package.json for Node.js projects, pyproject.toml for Python projects).

Built-in Providers¶

Commitizen includes several built-in version providers for common package management formats:

commitizen (Default)¶

The default version provider stores and retrieves the version from your Commitizen configuration file (e.g., pyproject.toml, .cz.toml, etc.).

Use when:

You want to keep version management separate from your package manager
Your project doesn't use a standard package manager
You need maximum flexibility in version management

Configuration:

[tool.commitizen]
version_provider = "commitizen"
version = "0.1.0"  # Required when using this provider

scm¶

Fetches the version from Git tags using git describe. This provider only reads version information and never writes it back to files. It's designed to work with tools like setuptools-scm or other package manager *-scm plugins that derive version numbers from Git history.

Use when:

You're using setuptools-scm or similar tools
You want version numbers derived from Git tags
You don't want Commitizen to modify any files for version management

Configuration:

[tool.commitizen]
version_provider = "scm"
# No version field needed - it's read from Git tags

Note

The scm provider is read-only. When you run cz bump, it will create a Git tag but won't update any files. This is intentional and works well with tools that derive versions from Git tags.

pep621¶

Manages version in pyproject.toml under the project.version field, following PEP 621 standards.

Use when:

You're using a modern Python project with PEP 621-compliant pyproject.toml
You want version management integrated with your Python project metadata

Configuration:

[tool.commitizen]
version_provider = "pep621"

Example pyproject.toml:

[project]
name = "my-package"
version = "0.1.0"  # Managed by Commitizen

poetry¶

Manages version in pyproject.toml under the tool.poetry.version field, which is used by the Poetry package manager. This approach is recommended only for users running Poetry versions earlier than 2.0 or relying on Poetry-specific features. For most users on Poetry 2.0 or later, it is recommended to use pep621 instead. Read More

Use when:

You're using Poetry < 2.0 as your Python package manager
You're using Poetry >= 2.0 as your Python package manager, but don't need poetry-specific features
You want Commitizen to manage the version that Poetry uses

Configuration:

[tool.commitizen]
version_provider = "poetry"

Example pyproject.toml:

[tool.poetry]
name = "my-package"
version = "0.1.0"  # Managed by Commitizen

uv¶

Manages version in both pyproject.toml (project.version) and uv.lock (package.version for the matching package name). This ensures consistency between your project metadata and lock file.

Note

Even though uv follows PEP 621 format, pep621 does not manage the version in uv.lock. uv is still suggested for uv users.

Use when:

You're using uv as your Python package manager
You want version synchronization between pyproject.toml and uv.lock

Configuration:

[tool.commitizen]
version_provider = "uv"

cargo¶

Manages version in both Cargo.toml (package.version) and Cargo.lock (package.version for the matching package name). This ensures consistency between your Rust project's manifest and lock file.

Use when:

You're working with a Rust project using Cargo
You want Commitizen to manage Rust package versions

Configuration:

[tool.commitizen]
version_provider = "cargo"

Example Cargo.toml:

[package]
name = "my-crate"
version = "0.1.0"  # Managed by Commitizen

npm¶

Manages version in package.json and optionally synchronizes with package-lock.json and npm-shrinkwrap.json if they exist.

Use when:

You're working with a Node.js/JavaScript project
You want Commitizen to manage npm package versions

Configuration:

[tool.commitizen]
version_provider = "npm"

Example package.json:

{
  "name": "my-package",
  "version": "0.1.0"
}

composer¶

Manages version in composer.json under the version field, used by PHP's Composer package manager.

Use when:

You're working with a PHP project using Composer
You want Commitizen to manage Composer package versions

Configuration:

[tool.commitizen]
version_provider = "composer"

Example composer.json:

{
  "name": "vendor/package",
  "version": "0.1.0"
}

Provider Comparison Table¶

Provider File(s) Modified Read-Only Best For

commitizen	Commitizen config file	No	General use, flexible projects
scm	None (reads from Git tags)	Yes	setuptools-scm users
pep621	pyproject.toml (project.version)	No	Modern Python (PEP 621)
poetry	pyproject.toml (tool.poetry.version)	No	Poetry projects
uv	pyproject.toml + uv.lock	No	uv package manager
cargo	Cargo.toml + Cargo.lock	No	Rust/Cargo projects
npm	package.json (+ lock files)	No	Node.js/npm projects
composer	composer.json	No	PHP/Composer projects

Creating Custom Version Providers¶

If none of the built-in providers meet your needs, you can create a custom version provider by extending the VersionProvider base class and registering it as a plugin.

Step 1: Create Your Provider Class¶

Create a Python file (e.g., my_provider.py) that extends VersionProvider:

my_provider.pyfrom pathlib import Path
from commitizen.providers import VersionProvider


class MyProvider(VersionProvider):
    """
    Custom version provider that reads/writes from a VERSION file.
    """

    def get_version(self) -> str:
        """Read version from VERSION file."""
        version_file = Path("VERSION")
        if not version_file.is_file():
            return "0.0.0"
        return version_file.read_text().strip()

    def set_version(self, version: str) -> None:
        """Write version to VERSION file."""
        version_file = Path("VERSION")
        version_file.write_text(f"{version}\n")

Step 2: Register as an Entry Point¶

Register your provider using the commitizen.provider entry point. You can do this in your setup.py, setup.cfg, or pyproject.toml:

Using pyproject.toml (recommended):

pyproject.toml[project]
name = "my-commitizen-provider"
version = "0.1.0"
dependencies = ["commitizen"]

[project.entry-points."commitizen.provider"]
my-provider = "my_provider:MyProvider"

Using setup.py (for legacy setup):

setup.pyfrom setuptools import setup

setup(
    name="my-commitizen-provider",
    version="0.1.0",
    py_modules=["my_provider"],
    install_requires=["commitizen"],
    entry_points={
        "commitizen.provider": [
            "my-provider = my_provider:MyProvider",
        ]
    },
)

Step 3: Install and Use¶

Install your provider package:
- Once your custom Commitizen provider is packaged and published (for example, to PyPI), install it like any standard Python package:
  
  pip install my-commitizen-provider
- If you want to use the provider directly from the current project source (during development), install it in editable mode (See pip documentation):
  
  pip install -e .
Configure Commitizen to use your provider:

[tool.commitizen]
version_provider = "my-provider"

Provider Implementation Guidelines¶

When creating a custom provider, keep these guidelines in mind:

get_version() should return a string representing the current version. If no version is found, you can return "0.0.0" or raise an appropriate exception.
set_version(version: str) should write the version to your chosen storage location. The version string will be properly formatted according to your version_scheme setting.
The provider has access to self.config, which is a BaseConfig instance containing all Commitizen settings.
For file-based providers, consider using the FileProvider or JsonProvider/TomlProvider base classes from commitizen.providers.base_provider to simplify implementation.

Example: JSON-based Provider¶

Here's a more complete example using the JsonProvider base class:

json_version_provider.pyfrom commitizen.providers.base_provider import JsonProvider


class JsonVersionProvider(JsonProvider):
    """
    Version provider that uses a custom version.json file.
    """

    filename = "version.json"

    def get(self, document):
        """Extract version from JSON document."""
        return document["version"]

    def set(self, document, version):
        """Set version in JSON document."""
        document["version"] = version

This example leverages the JsonProvider base class, which handles file reading, writing, and JSON parsing automatically.

Choosing the Right Provider¶

Select a version provider based on your project's characteristics:

Python projects
- with uv: Use uv
- with pyproject.toml that follows PEP 621: Use pep621
- with Poetry: Use poetry
- setuptools-scm: Use scm
Rust projects: Use cargo
Node.js projects: Use npm
PHP projects: Use composer
Other cases or custom needs: Use commitizen (default) or create a custom provider

Remember that you can always use version_files in combination with any provider to update additional files during version bumps, regardless of which provider you choose for reading/writing the primary version.

April 5, 2026