Skip to content

How to set up prek 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.

Use prek for Git hooks in a new Python project. It supports .pre-commit-config.yaml, so existing hook repositories and configurations remain usable. pre-commit remains an alternative; its setup instructions cover the original runner.

Install prek and the Git hook

Git must be installed and the project must be a Git repository. Run git init first if needed, then add the runner to the project:

uv add --dev prek
uv run prek install

The --dev flag marks prek 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 prek in the development group and lockfile, and an installed Git hook that runs on git commit.

Replace an existing pre-commit shim

After adding prek as described in Install prek and the Git hook, replace an existing pre-commit shim:

uv run prek install -f

Expect the Git shim to invoke prek. Keep the existing .pre-commit-config.yaml; remove the old runner dependency only when no remaining workflow needs it.

Creating the configuration file

prek reads the same .pre-commit-config.yaml format as pre-commit. Here is a starting configuration that uses Ruff for linting and formatting:

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

The ruff-check hook runs the linter with auto-fix enabled. The ruff-format hook runs the formatter. They execute in order, so linting fixes are applied before formatting.

Tip

Run uv run prek update to update all hook versions to their latest releases.

Adding more hooks

Trailing whitespace and file 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

Using prek’s built-in hooks

prek ships with Rust-native implementations of common hooks that require no external toolchain. Use repo: builtin to access them:

repos:
  - repo: builtin
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml

Built-in hooks run faster than their Python equivalents because they skip virtual environment setup entirely.

Type checking with ty

ty has an official hook at astral-sh/ty-pre-commit. prek reads the same configuration, so the pre-commit repo works unchanged:

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

The hook runs ty through uv, so dependencies in your pyproject.toml (including type stubs) are resolvable by ty. It checks the whole project rather than only the changed files. Pass args: [--isolated] to skip writing a lockfile or virtual environment.

Type checking with mypy

To run mypy as a hook:

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v2.1.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]

A complete configuration

Combining built-in hooks with Ruff:

repos:
  - repo: builtin
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml

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

Running hooks manually

After staging the intended new files, run all hooks against every tracked file in the repository:

$ uv run prek run --all-files

Expect the first run to prepare remote hook environments and show a result for each hook. If hooks modify files, inspect and stage the intended changes, then rerun.

To run a specific hook:

$ uv run prek run ruff-check --all-files

To list all configured hooks:

$ uv run prek list

Skipping hooks temporarily

To bypass hooks for a single commit:

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

Use this sparingly. 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 prek in CI

Run hooks in CI to catch anything contributors skip locally. In a GitHub Actions workflow:

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

Troubleshooting

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

$ uv run prek install

To clear cached hook environments (useful after updating Python or hook versions):

$ uv run prek cache clean
Last updated on