> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/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:

<Steps>
  <Step title="Add hook to .pre-commit-config.yaml">
    ```yaml theme={null}
    repos:
      - repo: https://github.com/astral-sh/uv-pre-commit
        rev: 0.10.8
        hooks:
          - id: uv-lock
    ```
  </Step>

  <Step title="Install pre-commit hooks">
    ```bash theme={null}
    pre-commit install
    ```
  </Step>

  <Step title="Test the hook">
    ```bash theme={null}
    # Make a change to pyproject.toml
    git add pyproject.toml
    git commit -m "Update dependencies"
    # uv-lock will run automatically and update uv.lock
    ```
  </Step>
</Steps>

## Export Requirements

Keep a `requirements.txt` file in sync with your `uv.lock` file:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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

<Warning>
  Always pin to a specific uv version using the `rev` field to ensure reproducible builds.
</Warning>

```yaml theme={null}
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

```yaml theme={null}
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.10.8
    hooks:
      - id: uv-lock
```

### Legacy Project with Requirements Files

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
pre-commit run --all-files
```

Run specific hook:

```bash theme={null}
pre-commit run uv-lock --all-files
```

Run on specific files:

```bash theme={null}
pre-commit run --files pyproject.toml
```

## Troubleshooting

### Hook Not Running

Ensure pre-commit is installed:

```bash theme={null}
pre-commit install
```

### Update Hook Versions

Update to the latest hook versions:

```bash theme={null}
pre-commit autoupdate
```

### Skip Hooks Temporarily

Skip hooks for a single commit:

```bash theme={null}
git commit --no-verify
```

Or set the `SKIP` environment variable:

```bash theme={null}
SKIP=uv-lock git commit -m "message"
```