Proposal: uv-synced Python hook environments (lockfile + groups)

[CarliJoy]

Related issues

Several issues appear to share the same missing primitive: creating/updating Python hook environments via a uv sync-style operation, instead of installing ad-hoc dependencies.

• support (language-specific) lockfiles #1311 — need for reproducible, lockfile-based hook environments (language-specific lockfiles / pinned resolution)
• Manage Python hook tool dependencies via pyproject.toml dependency group #1462 — manage hook tool dependencies (ruff/mypy/ty, etc.) via pyproject.toml dependency groups and keep them in a single lockfile
• Support running language: python hooks in the project's active venv #1485 — type checking (ty / mypy) typically requires all project dependencies to be installed (similar to Support installing dependencies from pyproject.toml as additional dependencies #780)
• Suggestion: Distinguished repo type for local running under uv #998 — local hooks using uv run work but feel like a workaround that could be first-class
• maybe Feature: Hook version sync #1054 could be soultion of using repo: local and run.
• Add uv-run hook astral-sh/uv-pre-commit#37 also wanting to use uv run for local repos

---

Problem

Current Python hook behaviour forces trade-offs:

• Type checkers often require the full dependency closure of the project so imports and types resolve. This makes “use active venv” attractive but less reproducible (Support running language: python hooks in the project's active venv #1485).
• Users want lockfile-backed reproducibility for hook environments, ideally using the same lockfile as the project (support (language-specific) lockfiles #1311).
• Users want a single source of truth where hook tool versions live in pyproject.toml and are locked in uv.lock (Manage Python hook tool dependencies via pyproject.toml dependency group #1462).
• Local repo workflows already rely on uv run, but this is not an explicit first-class model (Suggestion: Distinguished repo type for local running under uv #998).

---

Core idea

Add a uv-backed mode that:

1. creates a dedicated hook venv (as Python hooks already do),
2. populates it via lockfile-driven sync (uv.lock) using defined dependency groups in frozen mode.

Or put differently: make using prek with uv-based projects feel like using uv.

---

Option A — new language variant python-uv

Introduce a new language (name bikesheddable) meaning:

“Create and populate the hook environment using uv sync semantics.”

Example:

- repo: local
  hooks:
    - id: mypy
      name: mypy (uv-synced)
      language: python-uv
      entry: mypy
      dependency_groups: [typecheck]

Characteristics:

• python-uv implicitly uses uv.lock if present (frozen mode).
• No extra flags are required — behaviour is defined by the language.
• Enables defining a dedicated dependency group (e.g. typecheck) that installs everything required for type checking (Support running language: python hooks in the project's active venv #1485).
• Allows tool versions to live in pyproject.toml and be locked in uv.lock (Manage Python hook tool dependencies via pyproject.toml dependency group #1462).
• Makes local uv workflows first-class (Suggestion: Distinguished repo type for local running under uv #998).
• Since language can be overridden via prek.toml / .pre-commit-config.yaml, hook-providing repos can publish normal Python hooks while consuming repos enforce lockfile usage by overriding the language.

---

Option B — extend language: python with lockfile + groups/extras

Instead of a new language, extend language: python with opt-in configuration.

Example:

- repo: local
  hooks:
    - id: mypy
      language: python
      entry: mypy
      lockfile: uv.lock
      dependency_groups: [typecheck]

Semantics:

• Setting lockfile switches environment population to uv sync-style behaviour.
• dependency_groups / extras select what is installed.
• Default behaviour remains unchanged if lockfile is not specified.

---

Lockfile handling

Initial scope:

• Only support uv.lock.

Future extension:

• Support additional lock formats (e.g. py.lock) without changing the high-level configuration model.

This directly addresses reproducibility concerns from #1311 while keeping the initial scope small.

---

Why this solves the linked issues

• support (language-specific) lockfiles #1311 (lockfiles) — hook environments become reproducible and pinned to uv.lock.
• Manage Python hook tool dependencies via pyproject.toml dependency group #1462 (dependency groups) — hook tool dependencies can be defined in pyproject.toml and locked once.
• Support running language: python hooks in the project's active venv #1485 (type checking) — instead of using the active venv, hooks can create a fast, dedicated uv-synced environment containing all required dependencies.
• Suggestion: Distinguished repo type for local running under uv #998 (local uv workflows) — uv-managed hook environments become first-class rather than relying on uv run patterns.

I tend to option A.

[nathanjmcdougall]

Thanks for compiling these linked issues. I mentioned this in one of them, just to give a nod to an existing solution/design.

You can keep the existing prek/pre-commit syntax but use a tool to enforce a sync.

The one I use is 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.

It's possible that prek could come with a built-in tool which does the same thing and would work in the same way.

[CarliJoy]

@nathanjmcdougall

This tools follow an interesting idea. But:

• They add quite a lot of overhead as they need to update the pre-commit config with all changes of the uv.lock/pyproject.toml deps
• The won't respect the uv.lock of foreign (non local) repositories so it is not solution for support (language-specific) lockfiles #1311
• Adding all projects depenencies for to have mypy working will create rather larger pre-commit-configs on larger projects.
• In general they go against the single source of truth idea and seem to be more workaround.

Still I see the value in this kind of solution and just thinking about this a simple solution poped into my mind. I will add a comment in #1054 to describe it.

[ssbarnea]

Note that this is already achievable by using system hook with "uv run --group foo tool-name" but is bit ugly, it would better to get native support for this.

[CarliJoy]

Note that this is already achievable by using system hook with "uv run --group foo tool-name" but is bit ugly, it would better to get native support for this.

Yes, see #998
But using uv run will use the venv of the project. This could lead to problems if hooks are executed in parallel with different groups.
It is better to have a dedicated/independent venv like prek does normally.
Thanks to uvs hard linking this won't consume much disk space.

[brendan-morin]

I actually quite like option B since the action mechanism is the same it's only the environment that's different but see either option as being a good feature.

[CarliJoy]

Thinking more about it I would argue more against option B.
The new option are not supported by pre-commit. So this would make hook config files incompatible with pre-commit in away that is hard to spot.
Where as using a new language makes it easier to find out, that this "language" is no supported by pre-commit-

@j178 Would you willing to merge an pull request that implements option A? (Don't want to start one if there is not chance to get it merged)

[j178]

Thanks! I haven’t had much time to invest in this lately, but it’s been on my mind from time to time. I still don’t have a clear idea of how we should solve it, so let’s not rush into opening a PR just yet.

There are two things I haven’t fully figured out:

• The original pre-commit intentionally designed hooks to be isolated from the project—even for “local” hooks. The PEP-723 implementation (Support PEP 723 scripts for Python hooks #529) kind of breaks that boundary. We need to decide whether we’re okay with completely dropping that limitation or if there’s a better way to handle it.
• We should be careful about adding new options at the hook level. Ideally, they should be generic enough to apply to all hooks, like something such as priority — rather than something very specific like dependency_groups. Maybe we can introduce a more general option (name TBD), like “language-specific-args” and put all language-specific settings under that.

[brendan-morin]

The original pre-commit intentionally designed hooks to be isolated from the project—even for “local” hooks.

I suppose the question I would have here is what is (or was) the benefit to that approach? It does appear this is a bit of an arbitrary implementation opinion (of which the original creator had many) that may have benefits in some use cases, but isn't unambiguously more correct way to go about this than a non-isolated approach, at least generically. I think from the number of related issues, there is a community desire for alternative behavior with less strict isolation.

That said, even if we wanted to continue to maintain isolated environments, there is no reason the isolated environment couldn't have its dependencies constrained or defined such that they match a local environment or some other dependency spec outside of .pre-commit-config.yaml. In fact, I would argue having standards-compliant lockfiles as the source of truth, where possible, for syncronizing development environments would be a best practice.

Ideally, they should be generic enough to apply to all hooks

In general, I think the term lockfile is pretty language agnostic, and many languages share this concept. While it wouldn't apply to all hook types, there are also other arguments that aren't strictly applicable to all hook types (e.g. pass_filenames). language-specific-args or similar is also fine and could have some benefit (e.g. could more easily allow different lockfile types or additional configuration for a specific language).