Manage Python hook tool dependencies via `pyproject.toml` dependency group

[pygarap]

"One uv.lock to rule them all"!

Summary

Add support for managing the Python tool dependencies used by hooks in .pre-commit-config.yaml via a dedicated dependency group in pyproject.toml, and ensure those dependencies are synced into the root uv.lock.

Motivation

In many repos, hooks reference Python tools (for example: ruff, rumdl, mypy, pytest, etc.). Today, those tool versions typically live outside the project dependency management flow, which can lead to:

• Duplicate version pinning across files.
• Drift between what CI installs and what developers have locally.
• A less reproducible setup when using uv with a lock file.

Centralizing these tool versions in pyproject.toml would make hook tooling easier to maintain and more consistent.

Proposed behavior

1. Declare hook tool dependencies in pyproject.toml

Allow users to define a dependency group named prek under [dependency-groups] (PEP 735 style), for example:

[dependency-groups]
prek = [
  "ruff>=0.11.13",
  "rumdl>=0.0.210",
]

Which can be added using uv add --group prek ruff.

2. Sync those dependencies into the root uv.lock

When the repo uses uv and has a root uv.lock, ensure the dependency-groups.prek dependencies are included and locked there, so the hook tooling environment is reproducible.

Expected outcome

• A single source of truth for Python hook tooling versions.
• Less duplication between .pre-commit-config.yaml and Python dependency management.
• A reproducible, locked set of hook tool dependencies via uv.lock.

Notes / scope

• This request is specifically about Python hook tooling dependencies (not non-Python tools).

[ssbarnea]

I am glad someone did the filing for this as it describes exactly my issue: the need to avoid duplicating tool versions management in two places.

For practical reasons like being able to use IDE plugins like ruff/mypy/.... we need to ensure that the development versions are tracked as python dependencies (pyproject, usually as uv 'lint' dependency group). But this means that we create a duplication between pre-commit hook config and our pyproject.toml/uv.lock, one that not kept in sync automatically.

For these reasons we started to convert some of the hooks into system hooks that run stuff like commands like uv run --group lint ruff ....

This workaround also has some downsides: prek and prek-action will not cache them properly. Also we need to be sure to manually install uv as prek does not expose uv to the system hooks.

[pygarap]

@ssbarnea This feature works best together with #1485!

[ulgens]

I am glad someone did the filing for this as it describes exactly my issue: the need to avoid duplicating tool versions management in two places.

@ssbarnea I'm aware my recommendation won't be the perfect solution here, but I use Renovate to handle the same problem. In some other similar cases, the situation is even worse: uv version can be defined in a Dockerfile, in a workflow file, and in git hooks config. I use this Renovate config to handle it.

---

About the idea itself, I can see where it's coming from, and the case defined is valid, but I'm not sure it's better to mix prek setup with pyproject.toml. git hooks can define separate dependencies, and can use different languages - package managers. Not sure how would we define an NPM dependency in pyproject.toml file. I feel the pyproject.toml support for dependencies would complicate things more than it helps.

[pygarap]

@ulgens

Thanks for the detailed feedback, and for sharing the Renovate approach.

Just to clarify the scope: this ticket is only about language: python hooks, where prek already manages the hook environment using uv. It’s not meant to affect any other hook languages or package managers.

Users would still define hooks exactly as they do today in .pre-commit-config.yaml (with repo, rev, and hook IDs). Nothing changes about how hooks are selected, fetched, or versioned.

What this proposal changes is only how prek installs the Python packages for Python hook environments. The idea is to optionally let prek source those Python-only dependencies from a dedicated dependency group in pyproject.toml (for example [dependency-groups].prek) so they’re included in the same root uv.lock.

So this is not trying to model npm (or Bun/Go/Rust/etc) dependencies in pyproject.toml. The goal is simply one uv.lock for the repo, covering both project deps and prek’s Python hook env deps, to avoid duplication and drift.

[ulgens]

So this is not trying to model npm (or Bun/Go/Rust/etc) dependencies in pyproject.toml.

Yep, sorry if I wasn't clear with my feedback. I think this is the problem: prek support multiple languages and ecosystems, and currently everything can be managed from a single place. Supporting a different config approach for only one ecosystem would create fragmention in config IMO.

[ssbarnea]

@ulgens You are right that is only for python language but if that proves to be a big success something similar can be done for node with yarn.lock in the long run. Many languages already have support for lockfiles.

[nathanjmcdougall]

I like this proposal, although I think it would be better to focus on integration with the lockfile rather than the specifics of a TOML integration (first-class support for a prek dependency group etc.). This is related to #1311. I think if designed correctly, then a similar functionality can be provided for any language ecosystem with a lockfile in the long-run, so focusing on Python to begin with isn't a big deal IMO.

In the interim, my solution for this use-case is to use sync-with-uv:

  - repo: https://github.com/tsvikas/sync-with-uv
    rev: v0.5.0
    hooks:
      - id: sync-with-uv

A similar solution is offered by sync-pre-commit-lock but I found it less configurable.

[CarliJoy]

@pygarap I already wrote somehting similar in #1311 (comment) but it not exactly the same usecase as you described here.

Therefore I opened #1675 that combines all use cases.

Are you open to closing this Issue in favour of #1675?