Skip to main content
Integrate uv into your pre-commit workflow to automatically update lock files, export requirements, and compile dependencies.

​
Available Hooks

The official astral-sh/uv-pre-commit repository provides three hooks:
  • uv-lock: Update uv.lock when pyproject.toml changes
  • uv-export: Export uv.lock to requirements.txt
  • pip-compile: Compile requirements files

​
Lock File Updates

Automatically update your uv.lock file when pyproject.toml changes:
1

Add hook to .pre-commit-config.yaml

repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: uv-lock
2

Install pre-commit hooks

pre-commit install
3

Test the hook

# Make a change to pyproject.toml
git add pyproject.toml
git commit -m "Update dependencies"
# uv-lock will run automatically and update uv.lock

​
Export Requirements

Keep a requirements.txt file in sync with your uv.lock file: 
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: uv-export
This hook will automatically export dependencies whenever the lock file changes.

​
Custom Export Options

Pass additional arguments to customize the export: 
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: uv-export
        args: [--no-hashes, --output-file, requirements.txt]

​
Compile Requirements

Compile requirements.in files to locked requirements.txt files: 
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: pip-compile
        args: [requirements.in, -o, requirements.txt]

​
Multiple Requirements Files

Compile different requirements files with multiple hook entries: 
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: pip-compile
        name: pip-compile requirements.in
        args: [requirements.in, -o, requirements.txt]

      - id: pip-compile
        name: pip-compile requirements-dev.in
        args: [requirements-dev.in, -o, requirements-dev.txt]
        files: ^requirements-dev\.(in|txt)$

​
Alternative File Matching

Customize which files trigger the hook: 
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: pip-compile
        args: [requirements-dev.in, -o, requirements-dev.txt]
        files: ^requirements-dev\.(in|txt)$

​
Complete Configuration Example

Here’s a comprehensive pre-commit setup using all three hooks: 
repos:
  # Python code formatting and linting
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  # uv hooks for dependency management
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      # Keep lock file updated
      - id: uv-lock

      # Export lock file to requirements.txt
      - id: uv-export
        args: [--no-hashes, --output-file, requirements.txt]

      # Compile development requirements
      - id: pip-compile
        name: pip-compile requirements-dev.in
        args: [requirements-dev.in, -o, requirements-dev.txt]
        files: ^requirements-dev\.(in|txt)$

  # Other useful hooks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

​
Version Pinning

Always pin to a specific uv version using the rev field to ensure reproducible builds.
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    # Pin to exact version
    rev: 0.10.8
    hooks:
      - id: uv-lock

​
Common Use Cases

​
Python Project with Lock File

repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: uv-lock

​
Legacy Project with Requirements Files

repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: pip-compile
        args: [requirements.in, -o, requirements.txt]
      - id: pip-compile
        name: pip-compile dev requirements
        args: [requirements-dev.in, -o, requirements-dev.txt]
        files: ^requirements-dev\.(in|txt)$

​
Project Exporting to Requirements

repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: uv-lock
      - id: uv-export
        args: [--no-dev, --no-hashes, -o, requirements.txt]

​
Running Hooks Manually

Run all hooks on all files: 
pre-commit run --all-files
Run specific hook: 
pre-commit run uv-lock --all-files
Run on specific files: 
pre-commit run --files pyproject.toml

​
Troubleshooting

​
Hook Not Running

Ensure pre-commit is installed: 
pre-commit install

​
Update Hook Versions

Update to the latest hook versions: 
pre-commit autoupdate

​
Skip Hooks Temporarily

Skip hooks for a single commit: 
git commit --no-verify
Or set the SKIP environment variable: 
SKIP=uv-lock git commit -m "message"

Build docs developers (and LLMs) love

Get started for freeTalk to us