conventional-pre-commit

What it is and what it does

conventional-pre-commit is a pre-commit hook that enforces Conventional Commits formatting on git commit messages. It integrates with the pre-commit framework to block commits that don't follow the pattern type(scope): subject, rejecting messages like "add a new feature" while accepting "feat: add a new feature". The hook supports customization through arguments to restrict allowed commit types (feat, fix, chore, etc.), enforce scope presence, define allowed scopes, and enable strict mode to disallow fixup and merge commits.

It can be deployed as a pre-commit hook in your repository's workflow or installed standalone via pip for command-line or programmatic use. The package has no runtime dependencies and integrates cleanly into existing development workflows. It provides clear error messages showing what went wrong and how to fix the commit message, with optional verbose output explaining the expected format.

Use it for:

• Enforce Conventional Commits across a team to enable automated changelog generation and semantic versioning.
• Validate commit message format in CI/CD pipelines by running the command-line tool on commit message files.
• Restrict commits to a specific set of types (e.g., feat, fix, docs) and require scope specification for better commit organization.
• Prevent non-compliant commits from entering the repository during local development via pre-commit hook integration.
• Use the Python API to validate commit messages programmatically in custom tooling or scripts.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pre-commit hook that validates git commit messages against Conventional Commits formatting rules, rejecting non-compliant messages and optionally enforcing scopes and custom commit types.

Yes. This is a low-friction, actively maintained tool that solves a real problem—enforcing commit message consistency—with no dependencies and permissive licensing. It's well-suited for teams adopting Conventional Commits. Install it if your project needs standardized commit messages for changelog automation or team discipline; skip it if you have no such requirement.

Install

conventional-pre-commit on PyPI

pip install conventional-pre-commit

uv add conventional-pre-commit

poetry add conventional-pre-commit

Installing conventional-pre-commit

Before you install

Low friction install with no runtime dependencies. Active maintenance with recent releases; last commit 2026-07-20 and latest release 2026-02-18 indicate ongoing support.

License in practice

Apache 2.0 permissive license allows free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install conventional-pre-commit

Add to .pre-commit-config.yaml:
repos:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v4.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

Then: pre-commit install --install-hooks

Or use directly in Python:
from conventional_pre_commit.format import is_conventional
print(is_conventional("feat: add new feature"))

Requires pre-commit framework to be installed and initialized in your repository; works with Python >= 3.8.

Verify before relying

• Whether custom type validation and scope enforcement work reliably across all git workflows and edge cases.
• Performance impact when used in repositories with large commit histories or frequent commits.

Package facts

Evidence: conventional_pre_commit-4.4.0-py3-none-any.whl

Keywords: git, pre-commit, conventional-commits

Tags

More Build Tools packages