pre-commit
raw JSON → 4.5.1 verified Tue May 12 auth: no python install: verified quickstart: verified
A framework for managing and maintaining multi-language pre-commit hooks. Current version: 4.5.1. Released on December 16, 2025. Maintained with regular updates.
pip install pre-commit Common errors
error pre-commit: command not found ↓
cause The `pre-commit` executable is not found in your system's PATH, often because it was installed in a virtual environment that is not currently active, or it was never installed globally or in the active environment.
fix
Activate your virtual environment (if using one) or ensure
pre-commit is installed and its executable is discoverable. For Python virtual environments, use source venv/bin/activate (Linux/macOS) or .\venv\Scripts\activate (Windows) before running pre-commit. If not installed, run pip install pre-commit. error An unexpected error has occurred: InvalidConfigError: ==> File .pre-commit-config.yaml ↓
cause The `.pre-commit-config.yaml` file contains syntax errors (e.g., incorrect indentation, invalid mapping values, or missing required keys) preventing `pre-commit` from parsing it correctly, or the file does not exist where expected.
fix
Carefully check your
.pre-commit-config.yaml for YAML syntax errors, especially indentation. Ensure the file is named .pre-commit-config.yaml and is located at the root of your repository. Use a YAML linter or validator to identify specific issues. Example of a common error: mapping values are not allowed in this context. error fatal: cannot run .git/hooks/pre-commit: No such file or directory ↓
cause The Git pre-commit hook script, which `pre-commit` installs, either does not exist at the expected path (`.git/hooks/pre-commit`), has incorrect file permissions, or is referencing a non-existent internal script (e.g., from a removed Node.js `pre-commit` package).
fix
Run
pre-commit install to reinstall the Git hook script. Ensure the script at .git/hooks/pre-commit has executable permissions (chmod +x .git/hooks/pre-commit). If the error persists and you previously used a different hook system (like Node.js pre-commit), manually remove the old hook file from .git/hooks/pre-commit. error CalledProcessError: command: ('python', '-mpip', 'install', '.') return code: 1 expected return code: 0 stdout: Executable 'python' not found ↓
cause A hook defined in your `.pre-commit-config.yaml` requires an executable (like `python`, `node`, etc.) that `pre-commit` cannot find in the isolated environment it sets up for that hook, or on the system's PATH.
fix
For Python hooks, ensure
default_language_version: python: python3 (or a specific version like python3.X) is set in your .pre-commit-config.yaml. For other languages, ensure the required tools are installed and accessible by pre-commit's environment. For local hooks (language: system), verify the executable is in your system's PATH. error pre-commit: We've failed to pass the specified git pre-commit hooks as the <hook_id> hook returned an exit code (1). ↓
cause One of your configured pre-commit hooks failed its checks (e.g., a linter found issues, a formatter detected unformatted code, or tests failed), causing it to exit with a non-zero status code.
fix
Review the output in your terminal to see which specific hook failed and the reasons for its failure. Correct the issues reported by the hook (e.g., fix linting errors, format the code, resolve test failures) and then attempt to commit again. If you temporarily need to bypass the hooks, use
git commit --no-verify (not recommended for general use). Warnings
breaking Editable installs may break due to changes in `__editable__` and `__path_hook__` attributes. ↓
fix Use non-editable installations or adjust tooling to handle new attributes.
gotcha Ensure that the `virtualenv` package is installed to create isolated environments for hooks. ↓
fix Install `virtualenv` using `pip install virtualenv`.
breaking Pre-commit hooks require Git to be installed on the system and the command must be run within a valid Git repository. ↓
fix Ensure Git is installed and configured on the system where pre-commit is run, and execute pre-commit commands from within a directory that is part of a Git repository.
breaking pre-commit hooks require Git to be installed and the command to be run within a Git repository. Failure to meet these conditions results in a 'git failed' error. ↓
fix Ensure that Git is installed in the environment and that the 'pre-commit' command is executed inside a Git repository.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - 0.00s 31.3M
3.10 slim (glibc) - - 0.00s 32M
3.11 alpine (musl) - - 0.00s 33.7M
3.11 slim (glibc) - - 0.00s 35M
3.12 alpine (musl) - - 0.00s 25.4M
3.12 slim (glibc) - - 0.00s 27M
3.13 alpine (musl) - - 0.00s 25.1M
3.13 slim (glibc) - - 0.00s 26M
3.9 alpine (musl) - - 0.00s 30.6M
3.9 slim (glibc) - - 0.00s 32M
Imports
- pre_commit
import pre_commit
Quickstart verified last tested: 2026-04-23
import os
# Install pre-commit
os.system('pip install pre-commit')
# Create a configuration file
with open('.pre-commit-config.yaml', 'w') as f:
f.write('repos:\n - repo: https://github.com/pre-commit/mirrors-black\n rev: v22.10.0\n hooks:\n - id: black\n')
# Install the git hook scripts
os.system('pre-commit install')
# Run hooks against all files
os.system('pre-commit run --all-files')