Skip to content

How to set up pre-commit hooks for a Python project

This guide assumes you have a Python project managed with uv. If you haven’t created a project yet, see the project creation tutorial.

pre-commit is a framework that manages Git hooks. It runs tools like linters and formatters automatically before each commit, catching problems before they reach version control. This guide walks through installing pre-commit, configuring hooks for a Python project, and integrating it with Ruff and mypy.

Tip

For a new project, use prek, which reads the same configuration files. Follow the prek setup guide. This page covers the original pre-commit runner for projects that use it.

Tip

Using Claude Code? The project setup tutorial covers prek alongside CLAUDE.md, hooks, and skills as a complete stack. To run these checks while Claude edits instead of waiting for commit time, see how to configure Claude Code to run your pre-commit hooks.

Installing pre-commit

Git must be installed and the project must be a Git repository. Run git init first if needed, then add pre-commit as a project dependency so the installed hook has a runner for later commits:

$ uv add --dev pre-commit
$ uv run pre-commit install

The --dev flag marks pre-commit as a development dependencyA package needed during development (testing, linting, formatting) that is not shipped to users of your project. Installed with the --dev flag. , keeping it out of production installs. uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first. Expect pre-commit in the development group and a Git hook at .git/hooks/pre-commit that runs automatically on git commit.

Creating the configuration file

pre-commit reads its configuration from a .pre-commit-config.yaml file in the project root. Here is a starting configuration that uses Ruff for linting and formatting:

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

The ruff-check hook runs the linter with auto-fix enabled, which also sorts imports when the I rule is enabled. The ruff-format hook runs the formatter. They execute in order, so linting fixes are applied before formatting.

Tip

Run uv run pre-commit autoupdate periodically to update hook versions to the latest releases.

Adding more hooks

Catch trailing whitespace and bad line endings

The pre-commit-hooks repository provides several lightweight checks:

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-added-large-files

These catch common issues: trailing whitespace, missing newlines at end of file, invalid YAML syntax, and accidentally committed large files.

Check types with ty

ty has an official pre-commit hook at astral-sh/ty-pre-commit:

  - repo: https://github.com/astral-sh/ty-pre-commit
    rev: v0.0.104
    hooks:
      - id: ty

The hook runs ty through uv, so dependencies declared in your pyproject.toml (including type stubs) are resolvable by ty without listing them again in the hook config. It checks the whole project rather than only the changed files, because a change in one module can surface type errors in another. To run without writing a lockfile or virtual environment, pass args: [--isolated].

Check types with mypy

To run mypy as a pre-commit hook:

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v2.3.0
    hooks:
      - id: mypy
        additional_dependencies: []

Note

mypy 2.0 changed several defaults that may surface new errors in code that passed under 1.x. See the mypy reference page for details. mypy 2.0 also requires Python 3.10 or newer as both a runtime and a target.

Add any type stub packages your project needs to additional_dependencies. For example, if your project uses requests:

        additional_dependencies: [types-requests]

Combine all hooks

A complete .pre-commit-config.yaml with linting, formatting, and type checking:

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-added-large-files

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

  - repo: https://github.com/astral-sh/ty-pre-commit
    rev: v0.0.104
    hooks:
      - id: ty

Replace the ty block with the mypy block from above if your project uses mypy instead.

Running hooks manually

After staging the intended new files, run all hooks against every tracked file in the repository (not just staged changes):

$ uv run pre-commit run --all-files

Expect hook environments to download on the first run, then a result for each hook. If a hook modifies files, inspect and stage the intended changes, then rerun.

To run a specific hook:

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

Skipping hooks temporarily

To bypass hooks for a single commit:

$ git commit --no-verify -m "WIP: work in progress"

Use this sparingly. Skipping hooks defeats the purpose of having them. AI coding agents reach for --no-verify more readily than humans do; see how to stop AI agents from bypassing pre-commit hooks for the defensive setup.

Using pre-commit in CI

pre-commit hooks run locally, but contributors might skip them. Running hooks in CI ensures every change is checked. Add this to a GitHub Actions workflow:

- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v10.3.3
- run: uv run pre-commit run --all-files

Fix hook failures

If hooks are not running on commit, verify the hook is installed:

$ uv run pre-commit install

If a hook fails because it cannot find dependencies, check that additional_dependencies is set correctly for hooks like mypy that need access to your project’s packages.

To clear the pre-commit cache (useful after updating Python or hook versions):

$ uv run pre-commit clean
Last updated on