How to set up prek hooks for a Python project
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 installThe --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 -fExpect 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-formatThe 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-filesUsing 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-yamlBuilt-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: tyThe 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-formatRunning 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-filesTroubleshooting
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