sync-with-uv

Overview

PEP 735 introduces dependency groups in pyproject.toml, allowing tools like black, ruff, and mypy to be managed centrally. However, when these tools are also used in pre-commit hooks, keeping versions in sync between uv.lock and .pre-commit-config.yaml/prek.toml can be tedious.

This package automatically updates the versions of dependencies in .pre-commit-config.yaml/prek.toml to match their versions in uv.lock, ensuring everything stays aligned and is managed from a single source. Any tool not specified in uv.lock remains managed by .pre-commit-config.yaml/prek.toml.

Simply add this pre-commit hook to your setup and enjoy consistent dependency management.

Usage

Recommended: Use as a pre-commit hook

Simply add these lines to your .pre-commit-config.yaml file:

- repo: https://github.com/tsvikas/sync-with-uv
  rev: main  # replace with the latest version
  hooks:
    - id: sync-with-uv

or to your prek.toml:

[[repos]]
repo = "https://github.com/tsvikas/sync-with-uv"
rev = "main"  # replace with the latest version
hooks = [{ id = "sync-with-uv" }]

[!NOTE] Place this hook after hooks that modify uv.lock (like uv-lock), and before hooks that read versions from .pre-commit-config.yaml/prek.toml (like sync-pre-commit-deps).

That's it! The hook syncs versions for any tool present in both your pre-commit config and uv.lock. To make a tool eligible, add it to your uv dependencies with uv add --group dev <tool-name>.

Alternative: Command Line Interface

For manual usage or CI/CD integration, install and run directly:

uv tool install sync-with-uv

# Update .pre-commit-config.yaml / prek.toml
sync-with-uv

# Preview changes only
sync-with-uv --diff

# Custom file paths
sync-with-uv -u custom-lock.toml
sync-with-uv -p custom-precommit.yaml
sync-with-uv -p custom-prek.toml

Syncing additional dependencies

Besides the rev of each hook, the tool can also sync version pins inside additional_dependencies (or any other dependency line). Because these lists can contain arbitrary packages, syncing is strictly opt-in per line: a dependency is only touched if its line carries a # sync-with-uv pragma comment.

- repo: https://github.com/adamchainz/blacken-docs
  rev: 1.16.0
  hooks:
    - id: blacken-docs
      additional_dependencies:
        - black==23.9.1  # sync-with-uv
        - some-other-lib==1.0.0  # left alone, no pragma

For every annotated line, the dependency is pinned to an exact version (==) from uv.lock, adding a specifier when the dependency has none, so the example above becomes black==<locked>. The package name, extras (like black[jupyter]), environment markers (like ; python_version < "3.11"), quoting, and the comment itself are preserved.

Because the pragma is an explicit request to sync a line, the tool errors (exit code 123) when an annotated line cannot be synced.

Advanced Configuration

The tool works out of the box with popular tools like black, ruff, and mypy, as well as commonly used mirrors for those tools. Most users don't need the settings below.

Mapping from repo URL to package name

[tool.sync-with-uv.repo-to-package]
# sync this repo with the `awesome-linter` package
"https://github.com/my-org/my-awesome-linter" = "awesome-linter"
# do not sync this repo, even if `cool-tool` is in `uv.lock`
"https://github.com/my-org/cool-tool" = ""

Mapping from repo URL to version tag format

[tool.sync-with-uv.repo-to-version-template]
# for example, this project uses `version_1.2.3` format for tags
"https://github.com/my-org/my-awesome-linter" = "version_${version}"

Contributing

Interested in contributing? See CONTRIBUTING.md for development setup and guideline.