SEO Title: How to Install and Configure pre-commit on Mac, Windows & Linux (2026)

Meta Description: Learn how to install and configure pre-commit Git hooks on macOS, Windows, Ubuntu, Debian, and RHEL. Includes installation commands, YAML configuration, automatic linting, formatting, CI/CD integration, and troubleshooting.

Focus Keywords: pre-commit installation, install pre-commit macOS, pre-commit Windows, pre-commit Ubuntu, pre-commit Linux, pre-commit Git hooks, pre-commit config YAML, pre-commit Terraform, pre-commit Python, pre-commit GitHub Actions

---

1. Introduction

Writing clean, secure, and maintainable code is an essential part of modern software development.

However, even experienced developers occasionally introduce issues such as trailing whitespace, incorrectly formatted code, invalid YAML files, debugging statements, oversized files, or accidentally committed credentials.

Finding these issues during code review or after merging changes can waste valuable development time.

This is where pre-commit becomes useful.

pre-commit is an open-source framework for managing Git hooks that automatically checks your code before a commit is created.

It can run formatting tools, linters, configuration validators, and security-related checks without requiring developers to manually execute each tool.

For example, when a developer executes:

git commit -m "Add new feature"Code language: JavaScript (javascript)

pre-commit can automatically:

• Remove trailing whitespace.
• Fix missing end-of-file newlines.
• Validate YAML, JSON, and TOML files.
• Check for unresolved Git merge conflicts.
• Identify certain accidentally included private keys.
• Prevent unexpectedly large files from being committed.
• Format Python or Terraform files when suitable hooks are configured.
• Run additional code-quality checks.

In this tutorial, we will install and configure pre-commit across macOS, Windows, and Linux, build a practical Git hook configuration, and integrate it into everyday development workflows.

2. What Is pre-commit?

pre-commit is a framework that manages and executes Git hooks.

Git hooks are scripts that run automatically when specific Git operations occur.

The most common example is the pre-commit hook, which runs before Git finalizes a commit.

Instead of maintaining custom scripts individually, pre-commit lets developers describe their required checks in a single configuration file:

.pre-commit-config.yamlCode language: CSS (css)

The framework downloads supported hooks, creates isolated environments, and executes those hooks against applicable files.

How pre-commit Works

Developer changes files
         |
         v
    git add files
         |
         v
      git commit
         |
         v
  Git pre-commit hook
         |
         v
  pre-commit framework
         |
         v
  Execute configured checks
         |
     +---+---+
     |       |
    PASS    FAIL
     |       |
     v       v
 Commit    Commit blocked
 created   Fix errors
                |
                v
           Stage changes
                |
                v
           Retry commit

Some hooks only report issues, while others automatically modify files to fix problems.

If a hook modifies a file, you generally need to stage the changes again before committing.

Why Use pre-commit?

Without pre-commit	With pre-commit
Developers manually run formatting commands	Formatting runs automatically
Invalid configuration may reach code review	Syntax errors can be detected before committing
Inconsistent coding styles	Consistent checks across contributors
More avoidable code-review comments	Many simple issues are corrected locally
Each developer maintains separate scripts	Shared configuration in Git
Accidental mistakes reach CI/CD	Many errors are caught earlier

Important: pre-commit is not a replacement for automated tests, code reviews, security scanning, or CI/CD pipelines. It provides an additional layer of checks earlier in the development lifecycle.

---

3. Prerequisites

Before installing pre-commit, ensure your system has the following components.

Requirement	Description
Operating system	macOS, Windows, or Linux
Git	Required for Git hook integration
Python	Python 3.11 or newer for pre-commit 4.7.0
Internet	Required to download packages and hook dependencies
Terminal	Bash, Zsh, PowerShell, or compatible terminal
Git repository	Required for installing project-specific hooks
Package manager	Homebrew, pipx, pip, or another supported method

pre-commit itself requires Python, but it can manage hooks written in many programming languages.

Check Git Installation

On macOS or Linux:

git --version

On Windows PowerShell:

git --version

Example output:

git version 2.x.xCode language: CSS (css)

If Git is missing, install it from:

https://git-scm.com/downloads

Check Python Installation

On macOS or Linux:

python3 --version

On Windows:

py --version

Expected version:

Python 3.11.xCode language: CSS (css)

Or newer.

Check Whether pre-commit Is Already Installed

pre-commit --version

If installed, the command returns a version such as:

pre-commit 4.7.0Code language: CSS (css)

Otherwise, follow the installation instructions below.

---

4. How to Install pre-commit on macOS

macOS users can install pre-commit using Homebrew, pipx, or Python pip.

For most Mac users, Homebrew is the recommended option.

Method 1: Install pre-commit Using Homebrew (Recommended)

Step 1: Open Terminal

Open Terminal from:

Applications → Utilities → Terminal

Step 2: Check macOS Version

sw_vers

Check processor architecture:

uname -m

Apple Silicon:

arm64

Intel Mac:

x86_64

Homebrew supports compatible pre-commit installations on both architectures.

Step 3: Check Homebrew

brew --version

If Homebrew is not installed, use its official installation instructions at:

https://brew.sh

The official installer command is:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Code language: JavaScript (javascript)

Review the script and follow the instructions displayed by the installer.

Step 4: Update Homebrew

brew update

Step 5: Install pre-commit

brew install pre-commit

Homebrew installs pre-commit and its required runtime dependencies.

Step 6: Verify Installation

pre-commit --version

Expected output format:

pre-commit 4.7.0Code language: CSS (css)

The actual version depends on the version available through Homebrew.

Step 7: Locate the Executable

which pre-commit

Or:

command -v pre-commit

Typical Apple Silicon Homebrew location:

/opt/homebrew/bin/pre-commit

Typical Intel Homebrew location:

/usr/local/bin/pre-commit

Step 8: Display Available Commands

pre-commit --help

pre-commit is now installed on macOS.

Method 2: Install pre-commit Using pipx

pipx is useful when you want to install Python command-line applications into isolated environments.

Step 1: Install pipx

brew install pipx

Step 2: Configure pipx PATH

pipx ensurepath

Open a new terminal if required.

Step 3: Install pre-commit

pipx install pre-commit

Step 4: Verify

pre-commit --version

Using pipx keeps the pre-commit application separate from your project’s Python dependencies.

Method 3: Install pre-commit Using pip

For a Python virtual environment:

python3 -m venv .venvCode language: CSS (css)

Activate it:

source .venv/bin/activate

Install pre-commit:

python -m pip install pre-commit

Verify:

pre-commit --version

Recommendation: Use Homebrew or pipx for a general workstation installation. Use a project virtual environment when you intentionally manage pre-commit as a project dependency.

---

5. How to Install pre-commit on Windows 10/11

Windows users can install pre-commit using Python and pipx.

This method works with PowerShell, Windows Terminal, and compatible Git development environments.

Step 1: Open PowerShell

Open Windows PowerShell or PowerShell 7.

Step 2: Check Python

py --version

Verify Python 3.11 or newer.

If Python is missing, download it from:

https://www.python.org/downloads/windows

When installing, enable the option to add Python to PATH if offered.

Open a new PowerShell window after installation.

Verify pip

py -m pip --version

If pip is missing:

py -m ensurepip --upgrade

Step 3: Install pipx

Run:

py -m pip install --user pipx

Configure its executable path:

py -m pipx ensurepath

Close and reopen PowerShell.

Verify:

pipx --version

Step 4: Install pre-commit

pipx install pre-commit

pipx creates an isolated Python environment for pre-commit and exposes its executable to your user account.

Step 5: Verify Installation

pre-commit --version

Display help:

pre-commit --help

Step 6: Locate the Executable

Get-Command pre-commit

Or:

where.exe pre-commitCode language: CSS (css)

This helps confirm which installation Windows is using.

pre-commit is now installed on Windows.

Alternative: Install Through a Python Virtual Environment

If you prefer a project-specific setup:

py -m venv .venvCode language: CSS (css)

Activate the environment:

.\.venv\Scripts\Activate.ps1Code language: CSS (css)

Install:

python -m pip install pre-commit

Verify:

pre-commit --version

If PowerShell blocks activation scripts because of an execution policy, you can invoke the environment’s Python directly:

.\.venv\Scripts\python.exe -m pip install pre-commitCode language: CSS (css)

And verify:

.\.venv\Scripts\pre-commit.exe --versionCode language: CSS (css)

This avoids modifying PowerShell’s execution policy.

Note: When Git invokes installed hooks, it must still be able to find the pre-commit executable. A user-wide pipx installation is often more convenient for Git hooks used across multiple projects.

---

6. How to Install pre-commit on Ubuntu and Debian

For Ubuntu and Debian, pipx is a good installation choice because it avoids interfering with system-managed Python packages.

Step 1: Check Linux Distribution

cat /etc/os-release

Check Python:

python3 --version

The current pre-commit version requires Python 3.11 or newer.

If your distribution’s default Python is older, install a supported Python release using your distribution’s approved repositories before continuing.

Step 2: Update Package Metadata

sudo apt update

Step 3: Install Dependencies

sudo apt install -y \
  git \
  python3 \
  python3-pip \
  python3-venv \
  pipx

Step 4: Configure pipx

pipx ensurepath

Start a new shell if necessary.

Step 5: Install pre-commit

pipx install pre-commit

Step 6: Verify Installation

pre-commit --version

Check executable location:

command -v pre-commit

Display help:

pre-commit --help

The installation is complete.

Alternative: Install pre-commit with APT

Some Debian-based distributions provide a pre-commit package through their repositories:

sudo apt install pre-commit

However, the distribution package may be older than the current upstream release.

Check:

apt-cache policy pre-commit

For the current upstream release, pipx is generally preferable.

Alternative: Install Using pip in a Virtual Environment

Create an isolated environment:

python3 -m venv ~/.venvs/pre-commitCode language: JavaScript (javascript)

Install:

~/.venvs/pre-commit/bin/python -m pip install pre-commitCode language: JavaScript (javascript)

Verify:

~/.venvs/pre-commit/bin/pre-commit --versionCode language: JavaScript (javascript)

To use this executable globally, you can create a symbolic link in a user-local bin directory:

mkdir -p ~/.local/binCode language: JavaScript (javascript)

ln -s ~/.venvs/pre-commit/bin/pre-commit ~/.local/bin/pre-commitCode language: JavaScript (javascript)

Ensure ~/.local/bin is included in your PATH.

This approach also avoids modifying system Python packages.

---

7. How to Install pre-commit on Fedora, RHEL, CentOS, and Rocky Linux

On Fedora, pipx can generally be installed using DNF.

For RHEL and compatible distributions where pipx is unavailable in the enabled repositories, a Python virtual environment is a useful alternative.

Method 1: Fedora Installation Using pipx

Step 1: Install Dependencies

sudo dnf install -y \
  git \
  python3 \
  python3-pip \
  pipx

Step 2: Configure pipx

pipx ensurepath

Open a new terminal.

Step 3: Install pre-commit

pipx install pre-commit

Step 4: Verify Installation

pre-commit --version

Method 2: RHEL/CentOS Installation Using a Virtual Environment

Step 1: Install Git and a Compatible Python Runtime

For systems with appropriate package repositories enabled:

sudo dnf install -y git python3 python3-pip

Check:

python3 --version

If the default Python is older than 3.11, install a supported newer version and use that interpreter for the following commands.

Step 2: Create a Virtual Environment

python3 -m venv ~/.venvs/pre-commitCode language: JavaScript (javascript)

Step 3: Install pre-commit

~/.venvs/pre-commit/bin/python -m pip install pre-commitCode language: JavaScript (javascript)

Step 4: Configure a Command Path

mkdir -p ~/.local/binCode language: JavaScript (javascript)

ln -s ~/.venvs/pre-commit/bin/pre-commit ~/.local/bin/pre-commitCode language: JavaScript (javascript)

Add it to Bash’s PATH if required:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrcCode language: PHP (php)

Reload:

source ~/.bashrc

Step 5: Verify Installation

pre-commit --version

pre-commit --help

Important: Available Python versions and package names vary across RHEL, CentOS Stream, Rocky Linux, and other RPM-based distributions. Do not replace the system Python interpreter merely to install pre-commit.

---

8. Configure pre-commit in a Git Repository

Installing the pre-commit application is only the first part of the setup.

You must also configure the hooks for each Git repository where you want them to run.

The following steps are the same on macOS, Windows, and Linux.

Step 1: Navigate to Your Git Repository

For an existing repository:

cd /path/to/your/project

On Windows PowerShell, an example is:

cd C:\Projects\my-app

If you want to create a new demonstration repository:

mkdir pre-commit-demo
cd pre-commit-demo
git init

Verify that you are inside a Git repository:

git status

If Git displays repository status information, continue.

Step 2: Create the pre-commit Configuration File

pre-commit reads its configuration from:

.pre-commit-config.yamlCode language: CSS (css)

The file must be placed in the root of your Git repository.

You can create a starter configuration using:

pre-commit sample-config

To save the generated configuration directly on macOS or Linux:

pre-commit sample-config > .pre-commit-config.yamlCode language: CSS (css)

On Windows, you can create or edit the file using VS Code:

code .pre-commit-config.yamlCode language: CSS (css)

Alternatively:

notepad .pre-commit-config.yamlCode language: CSS (css)

If the file does not exist, create it when prompted.

Step 3: Add a Practical Configuration

For a typical project, use the following configuration:

# .pre-commit-config.yaml

minimum_pre_commit_version: "4.0.0"

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace

      - id: end-of-file-fixer

      - id: check-yaml

      - id: check-json

      - id: check-toml

      - id: check-merge-conflict

      - id: check-case-conflict

      - id: detect-private-key

      - id: check-added-large-files
        args: [--maxkb=1024]Code language: PHP (php)

This is a language-neutral configuration suitable for many software projects.

Understanding the Configuration

Setting	Purpose
minimum_pre_commit_version	Enforces a minimum supported framework version
repos	Lists hook repositories
repo	Repository URL containing hooks
rev	Version, tag, or commit to use
hooks	Hooks enabled from that repository
id	Identifier of a particular hook
args	Additional command-line arguments
files	Regex matching files the hook should process
exclude	Regex excluding files from processing
stages	Git hook stages on which a hook should run

What Do These Hooks Check?

Hook	Function
trailing-whitespace	Removes trailing whitespace
end-of-file-fixer	Ensures a consistent final newline
check-yaml	Checks YAML syntax
check-json	Checks JSON syntax
check-toml	Checks TOML syntax
check-merge-conflict	Detects common unresolved merge conflict markers
check-case-conflict	Detects filenames that conflict on case-insensitive filesystems
detect-private-key	Detects certain private-key patterns
check-added-large-files	Prevents staged additions exceeding the configured size limit

In this example, --maxkb=1024 sets the added-file limit to 1,024 KB.

Security note: detect-private-key is not a comprehensive secret scanner. Consider a dedicated secret-scanning tool for broader credential detection.

Step 4: Validate the Configuration

Run:

pre-commit validate-config

If the command exits successfully without errors, the configuration is syntactically valid according to pre-commit’s configuration schema.

Step 5: Install the Git Hook

Execute:

pre-commit install

Example output:

pre-commit installed at .git/hooks/pre-commit

This installs the Git hook launcher for the current repository.

From this point onward, a normal git commit triggers configured pre-commit-stage hooks.

Important: This step is repository-specific. Every developer must install the hook in their local clone, unless their development environment already provides equivalent setup automation.

Step 6: Download and Prepare Hook Environments

You can initialize hook environments before your first commit:

pre-commit install-hooks

This downloads and prepares the required hook environments.

The initial run may take longer because hook dependencies must be installed.

Subsequent runs can reuse cached environments.

Step 7: Run Hooks Against All Files

Execute:

pre-commit run --all-files

This checks applicable Git-tracked files in the repository.

Example output:

Trim Trailing Whitespace........................Passed
Fix End of Files................................Passed
Check Yaml......................................Passed
Check JSON......................................Passed
Check Toml......................................Passed
Check for merge conflicts.......................Passed
Check for case conflicts.........................Passed
Detect Private Key.............................Passed
Check for added large files.....................PassedCode language: CSS (css)

The exact output depends on the files in your repository.

A hook may report Skipped when no files match its conditions.

---

9. Test pre-commit with a Real Git Commit

Now let’s confirm that pre-commit runs automatically.

Step 1: Create a Sample File

On macOS/Linux:

printf 'name: demo\n' > example.yamlCode language: JavaScript (javascript)

On Windows PowerShell:

Set-Content -Path example.yaml -Value "name: demo"Code language: JavaScript (javascript)

Step 2: Stage the Files

git add .pre-commit-config.yaml example.yamlCode language: CSS (css)

Step 3: Create a Commit

git commit -m "Add pre-commit configuration"Code language: JavaScript (javascript)

Before creating the commit, Git invokes the installed pre-commit hook.

If all checks pass, Git continues creating the commit.

If a check fails, the commit is normally blocked.

If the hook automatically fixes a file, review and stage the updated file before retrying.

For example:

git status

git diff

Then:

git add example.yamlCode language: CSS (css)

Retry:

git commit -m "Add pre-commit configuration"Code language: JavaScript (javascript)

If Git reports that your author identity is not configured, follow Git’s instructions to set user.name and user.email before retrying.

---

10. Essential pre-commit Commands

The following commands are useful for everyday development.

Command	Purpose
pre-commit --version	Display installed version
pre-commit --help	Show available commands
pre-commit sample-config	Generate a sample configuration
pre-commit validate-config	Validate configuration syntax
pre-commit install	Install Git hook launcher
pre-commit install-hooks	Prepare hook environments
pre-commit run	Run applicable hooks on staged files
pre-commit run --all-files	Run applicable hooks on all tracked files
pre-commit run check-yaml --all-files	Run one specific hook
pre-commit run --files example.yaml	Run applicable hooks on one file
pre-commit autoupdate	Update hook repository revisions
pre-commit clean	Remove cached hook environments
pre-commit gc	Remove unused cached repositories
pre-commit uninstall	Remove installed Git hook launcher

Run a Specific Hook

pre-commit run trailing-whitespace --all-files

Validate Only YAML Files

pre-commit run check-yaml --all-files

Run Against Specific Files

pre-commit run --files README.md example.yamlCode language: CSS (css)

Display More Information on Failed Hooks

pre-commit run --all-files --verbose

Show Diffs When Hooks Modify Files

pre-commit run --all-files --show-diff-on-failure

This is particularly useful in CI/CD pipelines.

---

11. Configure pre-commit for Python Projects

Python projects can use pre-commit to execute formatters and linters automatically.

Ruff provides Python linting and formatting functionality.

To configure Ruff, add the following repository to your existing .pre-commit-config.yaml:

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.16.10
    hooks:
      - id: ruff-check
        args: [--fix]

      - id: ruff-format

The version above is an example of a published Ruff hook release. Keep its pinned version aligned with the Ruff configuration and compatibility requirements of your project.

What Happens?

When Python files are committed:

1. Ruff checks the Python code.
2. Ruff applies supported automatic lint fixes.
3. Ruff formats the code.
4. pre-commit reports failures or modified files.
5. The developer reviews and stages any changes.

Run manually:

pre-commit run ruff-check --all-files

Format all applicable tracked Python files:

pre-commit run ruff-format --all-files

Recommendation: Keep the Ruff linting hook before the formatting hook when enabling --fix.

---

12. Configure pre-commit for Terraform Projects

For Infrastructure-as-Code projects, pre-commit can help maintain consistent Terraform formatting and perform additional checks.

A popular hook collection is:

https://github.com/antonbabenko/pre-commit-terraform

Add the following to your configuration:

  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.108.1
    hooks:
      - id: terraform_fmt

This example enables Terraform formatting.

Run Terraform Formatting

pre-commit run terraform_fmt --all-files

Add Terraform Validation

If your project needs additional Terraform validation, you can add:

      - id: terraform_validate

However, Terraform validation may require initialized working directories, provider plugins, module downloads, and suitable backend configuration.

Terraform and other required supporting tools must be available for these hooks.

For Windows users, WSL is often a practical environment for shell-oriented Terraform pre-commit hook integrations.

Best practice: Run fast formatting checks before commits, and place more expensive Terraform validation, linting, and security checks in CI/CD when appropriate.

---

13. Configure Different Git Hook Stages

pre-commit can manage more than the standard pre-commit Git hook.

It supports stages such as:

• pre-commit
• pre-push
• commit-msg
• pre-merge-commit
• post-checkout
• post-merge

Example: Install Both pre-commit and pre-push Hooks

pre-commit install \
  --hook-type pre-commit \
  --hook-type pre-push

For Windows PowerShell, use one line:

pre-commit install --hook-type pre-commit --hook-type pre-push

You can specify hook stages in your configuration.

For example:

default_install_hook_types:
  - pre-commit
  - pre-push

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
        stages: [pre-commit]

      - id: check-yaml
        stages: [pre-commit, pre-push]Code language: JavaScript (javascript)

With this configuration:

• Trailing whitespace checks run before commits.
• YAML validation runs before commits and pushes.

A git push will trigger the installed pre-push hook.

Remember that a hook’s configured stages and the Git hook launchers installed in the repository must both be correct for it to run automatically.

---

14. Exclude Files and Directories from pre-commit

Some files should not be formatted or checked automatically.

Common examples include:

• Generated files.
• Build outputs.
• Dependency directories.
• Large vendor directories.
• Compiled artifacts.

You can exclude paths using regular expressions.

Example:

exclude: |
  (?x)^(
    node_modules/|
    dist/|
    build/|
    vendor/|
    coverage/|
    \.venv/|
    \.terraform/
  )

Add this at the top level of .pre-commit-config.yaml.

For individual hooks:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
        exclude: ^generated/Code language: JavaScript (javascript)

This excludes files under generated/ from that specific hook.

Important: Exclusions use regular expressions and apply to the files pre-commit considers. They are not identical to .gitignore patterns.

---

15. Run pre-commit Automatically in GitHub Actions

Local Git hooks are useful, but developers can skip them or forget to install them.

For consistent team enforcement, run the same checks in CI/CD.

GitHub Actions is one option.

Step 1: Create the Workflow Directory

On macOS/Linux:

mkdir -p .github/workflows

On Windows PowerShell:

New-Item -ItemType Directory -Force -Path .github/workflowsCode language: PHP (php)

Step 2: Create a Workflow File

Create:

.github/workflows/pre-commit.yml

Add:

name: Pre-commit Checks

on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  pre-commit:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v7

      - name: Set up Python
        uses: actions/setup-python@v7
        with:
          python-version: "3.13"

      - name: Install pre-commit
        run: python -m pip install pre-commit==4.7.0

      - name: Validate configuration
        run: pre-commit validate-config

      - name: Run all hooks
        run: pre-commit run --all-files --show-diff-on-failureCode language: JavaScript (javascript)

This workflow:

1. Checks out the repository.
2. Configures Python.
3. Installs the specified pre-commit version.
4. Validates the configuration.
5. Executes configured hooks against applicable tracked files.

If a hook fails or modifies a file, the GitHub Actions job fails, allowing the developer to review the issue.

For stricter software supply-chain controls, pin GitHub Actions to reviewed commit SHAs and restrict the permissions available to workflow jobs.

Optional: Test Across Multiple Operating Systems

To verify cross-platform behavior, use:

strategy:
  matrix:
    os:
      - ubuntu-latest
      - windows-latest
      - macos-latest

runs-on: ${{ matrix.os }}

Add this matrix to the job and use the matrix variable instead of a single runs-on value.

Running checks in CI/CD helps ensure that contributors receive consistent results even when local hooks are missing.

---

16. How to Update pre-commit

There are two different kinds of updates:

1. Updating the pre-commit framework.
2. Updating hook versions in .pre-commit-config.yaml.

These are separate operations.

Update pre-commit on macOS

Homebrew:

brew update
brew upgrade pre-commit

pipx:

pipx upgrade pre-commit

Update pre-commit on Windows

For a pipx installation:

pipx upgrade pre-commit

Update pre-commit on Linux

For a pipx installation:

pipx upgrade pre-commit

For a virtual-environment installation:

~/.venvs/pre-commit/bin/python -m pip install --upgrade pre-commitCode language: JavaScript (javascript)

Update Configured Hook Versions

Run:

pre-commit autoupdate

This updates the hook repository revisions in .pre-commit-config.yaml to newer available versions.

After updating, run:

pre-commit validate-config

Then:

pre-commit run --all-files

Review the resulting changes before committing them.

Production recommendation: Avoid automatically accepting every hook upgrade. Review release notes and compatibility changes before rolling updated hooks out to a team.

---

17. Troubleshooting Common pre-commit Errors

The following table summarizes common installation and configuration problems.

Error or symptom	Possible cause	Recommended solution
pre-commit: command not found	Executable missing from PATH	Verify installation and PATH
pre-commit is not recognized	Windows PATH not refreshed	Restart PowerShell and check installation
No .pre-commit-config.yaml file was found	Configuration file missing	Create the file in the repository root
InvalidConfigError	Incorrect YAML or configuration format	Run pre-commit validate-config
git failed	Git unavailable or repository problem	Verify Git and repository status
externally-managed-environment	System Python managed by OS	Use pipx or a virtual environment
Permission denied	Installation or execution permissions	Check executable permissions
Failed to create environment	Python/runtime/dependency issue	Check required runtime and hook dependencies
Files were modified by this hook	Formatter changed files	Review and stage changes again
An unexpected error has occurred	Hook installation or execution failure	Inspect detailed output and pre-commit log
Hook never runs on commit	Git launcher not installed or custom hooks path	Reinstall and inspect Git hook configuration

Troubleshooting 1: pre-commit Command Not Found

On macOS/Linux:

command -v pre-commit

Check:

echo "$PATH"Code language: PHP (php)

For a pipx installation:

pipx listCode language: PHP (php)

Run:

pipx ensurepath

Open a new terminal and retry.

Troubleshooting 2: pre-commit Not Recognized on Windows

Check:

Get-Command pre-commit

Inspect pipx installations:

pipx listCode language: PHP (php)

Refresh PATH configuration:

py -m pipx ensurepath

Open a new PowerShell window.

Troubleshooting 3: Invalid Configuration

Example:

InvalidConfigError:
==> File .pre-commit-config.yamlCode language: PHP (php)

Check the YAML syntax and configuration schema.

Run:

pre-commit validate-config

Common mistakes include:

• Incorrect indentation.
• Missing repos entries.
• Invalid hook IDs.
• Invalid stage names.
• Incorrect YAML list formatting.
• Unsupported configuration properties.

Troubleshooting 4: Python Version Not Supported

Verify:

python3 --version

Or on Windows:

py --version

pre-commit 4.7.0 requires Python 3.11 or newer.

Install or select a compatible Python runtime, then reinstall pre-commit using that runtime.

Hook environments can have additional language-version requirements of their own.

Troubleshooting 5: Files Were Modified by This Hook

Example output:

Trim Trailing Whitespace................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hookCode language: JavaScript (javascript)

This does not necessarily mean the tool is broken.

The hook may have successfully fixed a formatting problem and intentionally stopped the commit.

Review the changes:

git diff

Stage the modified files:

git add .

Run checks again:

pre-commit run --all-files

Then retry the commit.

When working in an existing repository, stage only the files you intend to commit instead of using git add . indiscriminately.

Troubleshooting 6: pre-commit Does Not Execute During Git Commit

Check the Git hooks path:

git config --get core.hooksPathCode language: JavaScript (javascript)

A custom hooks directory may cause Git to ignore the normal .git/hooks directory.

Reinstall the launcher:

pre-commit install

If the repository uses a custom core.hooksPath, integrate pre-commit with that existing hook-management approach rather than overwriting another tool’s configuration without review.

Troubleshooting 7: Clear Broken Hook Environments

If a cached hook environment appears corrupted, run:

pre-commit clean

Then:

pre-commit install-hooks

Finally:

pre-commit run --all-files

This forces the required hook environments to be rebuilt.

Do not treat cache clearing as a fix for invalid credentials, unavailable dependencies, or broken configuration files.

---

18. How to Temporarily Skip pre-commit Hooks

Occasionally, a developer may need to skip a particular hook for a legitimate reason.

pre-commit supports the SKIP environment variable.

macOS/Linux

For example:

SKIP=check-yaml git commit -m "Temporary commit"Code language: JavaScript (javascript)

This skips only the configured hook with the specified ID.

Windows PowerShell

$env:SKIP = "check-yaml"

git commit -m "Temporary commit"

Remove-Item Env:\SKIPCode language: PHP (php)

Skip All Git Commit Verification Hooks

Git also supports:

git commit --no-verify -m "Temporary commit"Code language: JavaScript (javascript)

However, this bypasses applicable Git commit verification hooks, not just a single pre-commit check.

Best practice: Avoid bypassing checks except for clearly justified situations. CI/CD should independently enforce the project’s required checks.

---

19. How to Uninstall pre-commit

If you want to remove pre-commit from a repository, first remove the Git hook launcher.

Navigate to the repository:

cd /path/to/your/project

Execute:

pre-commit uninstall

This removes the installed pre-commit Git hook launcher.

You can then remove the application using the package manager that installed it.

macOS — Homebrew

brew uninstall pre-commit

macOS/Windows/Linux — pipx

pipx uninstall pre-commit

Ubuntu/Debian — APT

sudo apt remove pre-commit

Project Virtual Environment

If pre-commit is installed in an activated virtual environment:

python -m pip uninstall pre-commit

Removing the application does not automatically remove every repository configuration file.

If you no longer want the project configuration, remove .pre-commit-config.yaml separately and update the repository as appropriate.

---

20. pre-commit Installation Command Cheat Sheet

Operating system	Recommended installation
macOS Intel	brew install pre-commit
macOS Apple Silicon	brew install pre-commit
Windows 10/11	pipx install pre-commit
Ubuntu	pipx install pre-commit
Debian	pipx install pre-commit
Fedora	pipx install pre-commit
RHEL/CentOS	Install using pipx or an isolated Python virtual environment
macOS/Linux with pipx	pipx install pre-commit
Python virtual environment	python -m pip install pre-commit

Essential Configuration Commands

# Check version
pre-commit --version

# Generate sample configuration
pre-commit sample-config

# Validate configuration
pre-commit validate-config

# Install Git hook
pre-commit install

# Install hook environments
pre-commit install-hooks

# Run against all tracked files
pre-commit run --all-files

# Run on staged files
pre-commit run

# Update hook versions
pre-commit autoupdate

# Clear cached environments
pre-commit clean

# Remove installed Git hook
pre-commit uninstallCode language: PHP (php)

---

21. Frequently Asked Questions

Q1. Is pre-commit free and open source?

Yes. pre-commit is an open-source framework distributed under the MIT license.

Q2. Is pre-commit only for Python projects?

No. Although pre-commit is implemented in Python, it supports hooks for many languages and tools, including JavaScript, Python, Go, Ruby, and others.

Q3. Does pre-commit support Terraform?

Yes. Community hook collections provide Terraform formatting, validation, and other Infrastructure-as-Code checks.

Q4. Does pre-commit work on Windows?

Yes. pre-commit supports Windows and can be installed through Python tooling such as pipx.

Some individual hooks may require WSL or other platform-specific dependencies, so check the requirements of each hook.

Q5. Is pre-commit automatically enabled after installation?

No.

Installing the executable makes the command available, but you must configure it in your repository and run:

pre-commit install

Q6. Does pre-commit run automatically when I commit?

Yes, after the appropriate Git hook launcher is installed in that repository.

Q7. Does pre-commit check every file during each commit?

Normally, pre-commit-stage hooks operate on applicable staged files.

To check all applicable tracked files:

pre-commit run --all-files

Q8. Can pre-commit automatically fix code?

Yes. Many hooks can modify files to correct formatting or other supported issues.

Not every hook supports automatic fixes.

Q9. Can pre-commit detect secrets?

It can run hooks that detect certain secrets or private-key patterns.

For broader protection, integrate a dedicated secret scanner and server-side secret detection.

Q10. Should pre-commit run in CI/CD?

Yes. Running the same checks in CI/CD reduces the risk of bypassed or missing local hooks.

Q11. Can I run pre-commit without installing Git hooks?

Yes. With a configuration present, you can run:

pre-commit run --all-files

The Git launcher is required for automatic execution during commits, not for manual execution.

Q12. Does pre-commit replace code review?

No. It helps automate repetitive checks but does not replace human review of correctness, architecture, security, or maintainability.

---

22. Best Practices for Teams and Production Projects

For reliable adoption across development teams, follow these recommendations:

1. Keep .pre-commit-config.yaml under version control.
2. Pin hook repositories to reviewed versions or commit references.
3. Use the same configuration locally and in CI/CD.
4. Select fast hooks for the pre-commit stage.
5. Run expensive tests and scans in CI/CD or pre-push stages when appropriate.
6. Use pre-commit run --all-files when introducing new hooks to an existing repository.
7. Review automatic formatting changes before committing.
8. Avoid excluding large portions of the codebase without a clear reason.
9. Do not rely on local hooks alone for security enforcement.
10. Use standard, maintained hook collections rather than unnecessary custom scripts.
11. Review third-party hooks before executing them because hooks can run code on developer machines and CI runners.
12. Update hook versions through a controlled review process.
13. Document any platform-specific requirements for contributors.
14. Include pre-commit setup instructions in the project README or onboarding documentation.
15. Keep hook execution fast enough that developers do not routinely bypass it.

---

23. Conclusion

pre-commit is a practical tool for improving code consistency, reducing avoidable mistakes, and bringing automated quality checks earlier into the development workflow.

It works across macOS, Windows, and Linux and can be used with virtually any Git-based software project.

For most users, installation is straightforward:

macOS:

brew install pre-commit

Windows:

pipx install pre-commit

Linux:

pipx install pre-commit

Once installed, the essential setup process is:

# Create or configure .pre-commit-config.yaml

# Validate configuration
pre-commit validate-config

# Install the Git hook
pre-commit install

# Prepare hook environments
pre-commit install-hooks

# Run against all tracked files
pre-commit run --all-filesCode language: PHP (php)

From that point onward, supported hooks automatically execute when the corresponding Git events occur.

By combining local pre-commit hooks with CI/CD checks, development teams can catch common issues earlier, maintain consistent coding standards, and spend more time reviewing meaningful code changes rather than repetitive formatting problems.

---

Official Documentation and References

• pre-commit Official Website: https://pre-commit.com/
• pre-commit GitHub Repository: https://github.com/pre-commit/pre-commit
• pre-commit Releases: https://github.com/pre-commit/pre-commit/releases/latest
• Official pre-commit-hooks Collection: https://github.com/pre-commit/pre-commit-hooks
• Homebrew pre-commit Package: https://formulae.brew.sh/formula/pre-commit
• pipx Installation Documentation: https://pipx.pypa.io/latest/how-to/install-pipx.html
• Ruff pre-commit Hooks: https://github.com/astral-sh/ruff-pre-commit
• Terraform pre-commit Hooks: https://github.com/antonbabenko/pre-commit-terraform
• Git Documentation: https://git-scm.com/docs/githooks
• GitHub Actions Documentation: https://docs.github.com/en/actions

Last reviewed: October 20, 2026. Package versions, supported Python releases, hook dependencies, and installation methods may change. Always verify the official documentation before rolling out new versions in production environments.