Where Does Commitizen Store Its Config?
Commitizen (Python) reads .cz.toml and siblings or the tool.commitizen table in pyproject.toml, first match wins.
Last updated
Commitizen searches a fixed ladder: .cz.toml, cz.toml, then json and yaml twins, then the tool.commitizen table in pyproject.toml. First valid file wins outright, with cz init scaffolding whichever you pick.
Version bumps, changelog files and tag formats all key off that one file. Python projects usually fold it into pyproject.toml; polyglot repos keep a standalone .cz.toml so non-Python tooling never parses packaging metadata for release rules.
Where Commitizen stores this, by platform
[RepoDir]\.cz.toml
Version, tag format, changelog file, bump message. First match in the ladder wins; --config pins an exact file and errors if absent.
[RepoDir]/.cz.toml
Same order. The JS cz-cli cousin instead reads package.json config.commitizen.path, so check which Commitizen a repo means before editing.
[RepoDir]/.cz.toml
Same layout. cz bump --dry-run previews version and changelog writes without touching tags, which is the safe way to test new rules.
Frequently asked questions
My settings are ignored. What is wrong?
It uses the first file found in a fixed order (.cz.toml, cz.toml, .cz.json, cz.json, .cz.yaml, cz.yaml, then pyproject.toml). A stray .cz.json above your real config silently wins, so search upward when settings misbehave.
How do I force one exact config file?
Pass cz --config <path>. That file becomes the only source (missing file errors out), which pins CI to reviewed settings regardless of stray dotfiles.
Notice an outdated path? Let us know.