Pre-commit Integration

Use uv with pre-commit hooks to automate lock file updates and requirements management

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"