Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
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.
pre-commit --version
Debug
Known issues
gotchapre-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.fixSet `DISABLE_PRE_COMMIT_UV_PATCH=1` or `FORCE_PRE_COMMIT_UV_PATCH=1` in your environment as needed.
affects: All versions
gotchaWhile `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.fixConsider 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`.
affects: All versions
gotchaInitial 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.fixBe 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.
affects: All versions
gotchaThere 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.fixIf 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.
affects: All versions (for `uv-lock` hook from `astral-sh/uv-pre-commit`)
Errors
Common errors & fixes
uv pip install -g pre-commit error: unexpected argument '-g' found
`uv pip install` does not support a global installation flag (`-g`) as `uv` manages global tools differently.
fixInstall `pre-commit` and `pre-commit-uv` as a globally managed tool using `uv tool install pre-commit --with pre-commit-uv`.
[ERROR] uv-sync is not present in repository https://github.com/astral-sh/uv-pre-commit. Typo?
The `uv-sync` hook, or another specified hook, is not available in the `rev` (version) of the `uv-pre-commit` repository defined in your `.pre-commit-config.yaml` file, likely due to an outdated or incorrect version.
fixUpdate the `rev` in your `.pre-commit-config.yaml` to the latest stable version of `uv-pre-commit` (e.g., `rev: <latest_version>`) and run `pre-commit autoupdate`.
warning: `VIRTUAL_ENV=/path/to/cache/py_env-python3.X` does not match the project environment path `.venv` and will be ignored.
`uv` is detecting an active `VIRTUAL_ENV` environment variable, which `pre-commit` sets for its internal hook environment, but `uv` prefers to manage its own project-level virtual environment, leading to this informational warning.
fixThis warning can often be safely ignored within `pre-commit`'s internal hooks. To explicitly suppress it, you can add `env: { VIRTUAL_ENV: "" }` to the specific hook's configuration in `.pre-commit-config.yaml` to clear the environment variable for that hook's execution. The uv-lock hook updates uv.lock but does not commit it
The `uv-lock` hook (or `pip-compile`) modifies `uv.lock` or `requirements.txt` to keep it updated, but `pre-commit` is designed to fail when a hook modifies staged files, requiring explicit user action to stage the changes.
fixAfter the `pre-commit` hook fails and updates the `uv.lock` file, stage the modified `uv.lock` (e.g., `git add uv.lock`) and then recommit. This is `pre-commit`'s intended fail-fast behavior to ensure generated files are committed.
pre-commit: command not found
The `pre-commit` executable is not in your system's PATH, or the Python virtual environment where `pre-commit` was installed is not currently active.
fixIf installed with `uv tool install pre-commit --with pre-commit-uv`, ensure `uv`'s tool binary directory is in your system's PATH. If `pre-commit` was installed with `pip` into a virtual environment, activate that virtual environment before running `pre-commit` commands.
Upgrade
Version history
4.2.1latest on PyPI · released Feb 18, 2026
Audit
Dependencies
pre-commitrequiredpre-commit-uv is a plugin/patch for the pre-commit framework.
uvrequiredpre-commit-uv leverages uv for faster virtual environment and package management.