Commitizen is a powerful release management tool that helps teams maintain consistent and meaningful commit messages while automating version management.
By enforcing standardized commit conventions (defaulting to Conventional Commits), Commitizen helps teams:
With just a simple cz bump command, Commitizen handles:
This standardization makes your commit history more readable and meaningful, while the automation reduces manual work and potential errors in the release process.
Before installing Commitizen, ensure you have:
The recommended way to install Commitizen is using pipx or uv, which ensures a clean, isolated installation:
Using pipx:
Using uv:
(For macOS users) Using Homebrew:
You can add Commitizen to your Python project using any of these package managers:
Using pip:
Using conda:
Using Poetry:
Using uv:
Using pdm:
To get started, run the cz init command. This will guide you through the process of creating a configuration file with your preferred settings.
Create standardized commits using:
To sign off your commits:
For more commit options, run cz commit --help.
The most common command you'll use is:
This command:
You can customize:
For all available options, see the bump command documentation.
This command is particularly useful for automation scripts and CI/CD pipelines.
For example, you can use the output of the command cz changelog --dry-run "$(cz version -p)" to notify your team about a new release in Slack.
Commitizen can automatically validate your commit messages using pre-commit hooks.
Add to your .pre-commit-config.yaml:
Install the hooks:
| commitizen | commit-msg |
| commitizen-branch | pre-push |
Note: Replace master with the latest tag to avoid warnings. You can automatically update this with:
For more details about commit validation, see the check command documentation.
Commitizen provides a comprehensive CLI with various commands. Here's the complete reference:
| cz init | Initialize Commitizen configuration | - |
| cz commit | Create a new commit | cz c |
| cz bump | Bump version and update changelog | - |
| cz changelog | Generate changelog | cz ch |
| cz check | Validate commit messages | - |
| cz version | Show version information | - |
For each command, you can get detailed help by adding --help:
For more details, visit our documentation site.
Commitizen supports command-line completion through argcomplete, which is automatically installed as a dependency. This feature provides intelligent auto-completion for all Commitizen commands and options.
If you installed Commitizen globally (e.g., using pipx or brew), you can enable global completion:
For a user-specific installation that persists across sessions:
For one-time activation in your current shell session:
After installation, you can verify the completion is working by:
For more detailed information about argcomplete configuration and troubleshooting, visit the argcomplete documentation.
These are our cool sponsors!
February 14, 2026