---
id: conventional-pre-commit
version: "4.4.0"
license: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# conventional-pre-commit — A pre-commit hook that checks commit messages for Conventional Commits formatting.

License: permissive · Maintenance: active · Downloads: 135.2K/mo

## 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 above — 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

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

- License: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 135.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

conventional commits validation, pre-commit hook commit message, git commit message linter, enforce commit message format, conventional commits checker, git-workflow, commit-linting, conventional-commits

[View on SkillFed](https://skillfed.io/packages/conventional-pre-commit) · [View on PyPI](https://pypi.org/project/conventional-pre-commit/)