pre-commit-uv

Warnings

• gotcha pre-commit-uv operates by patching `pre-commit` to use `uv`. If you encounter unexpected behavior or wish to temporarily disable this patching, you can set the `DISABLE_PRE_COMMIT_UV_PATCH` environment variable. Conversely, `FORCE_PRE_COMMIT_UV_PATCH` can be used to force patching if automatic detection fails.
  Fix: Set `DISABLE_PRE_COMMIT_UV_PATCH=1` or `FORCE_PRE_COMMIT_UV_PATCH=1` in your environment as needed.
• gotcha While `pre-commit-uv` significantly speeds up the *internal package management* for `pre-commit` hooks, it does not automatically synchronize the `rev` (version) fields for external hook repositories defined in your `.pre-commit-config.yaml` with your project's `pyproject.toml` or `uv.lock` file. This can lead to version drift where local tools and pre-commit hooks use different versions of the same dependency.
  Fix: Consider using supplementary tools like `sync-with-uv` (e.g., `github.com/tsvikas/sync-with-uv`) or `sync-pre-commit-with-uv` (e.g., `github.com/ewjoachim/sync-pre-commit-with-uv`) as an additional pre-commit hook to automatically update `rev` values based on your `uv.lock`.
• gotcha Initial runs of any `pre-commit` hook (even with `pre-commit-uv`) may still take some time as `pre-commit` downloads and installs the necessary tools into isolated environments. `pre-commit-uv` primarily optimizes subsequent runs and the initial *seed* operation.
  Fix: Be aware that the very first execution of a new hook will involve setup time. Subsequent runs will leverage `uv`'s speed and `pre-commit`'s caching.
• gotcha There are distinct tools related to `uv` and `pre-commit`. `pre-commit-uv` (this library) patches `pre-commit` to use `uv`. A separate project, `astral-sh/uv-pre-commit`, provides specific hooks (like `uv-lock`, `uv-export`) for `uv` itself. If you use the `uv-lock` hook from `astral-sh/uv-pre-commit`, be aware it might update your `uv.lock` file but not automatically add it to the Git index, leading to an unstaged change after the commit.
  Fix: If using the `uv-lock` hook and desiring automatic staging, you might need to manually add `git add uv.lock` or configure a custom hook to stage the changes if `uv-lock` itself does not. Alternatively, review the hook's intended behavior.

Install

• pip install pre-commit-uv Standard pip installation
• pipx install pre-commit pipx inject pre-commit pre-commit-uv Recommended for global installation via pipx
• uv tool install pre-commit --with pre-commit-uv --force-reinstall Recommended for installing pre-commit with pre-commit-uv using uv

Quickstart

To get started, install `pre-commit` using `uv`'s tool installer, ensuring `pre-commit-uv` is included as a plugin. Once installed, configure your `.pre-commit-config.yaml` with your desired hooks. `pre-commit-uv` automatically patches `pre-commit` to use `uv` for managing the hook environments, improving performance without changes to your hook configurations.

# 1. Install uv (if you haven't already)
# curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install pre-commit with pre-commit-uv using uv's tool installer
uv tool install pre-commit --with pre-commit-uv

# 3. Initialize git repository (if not already one)
git init

# 4. Create a .pre-commit-config.yaml file in your project root
#    (e.g., to use ruff for formatting and linting)
# .pre-commit-config.yaml
# ---
# repos:
#   - repo: https://github.com/astral-sh/ruff-pre-commit
#     rev: v0.4.0 # Use 'pre-commit autoupdate' to keep this updated
#     hooks:
#       - id: ruff
#         args: [--fix, --exit-non-zero-on-fix]
#       - id: ruff-format

# 5. Install the git hooks
pre-commit install

# 6. (Optional) Run all hooks manually once
pre-commit run --all-files

# Now, pre-commit will automatically use uv when running hooks.