/migration-patterns:black-to-ruff-format

Migrate from black to ruff format — Ruff's drop-in Black-compatible formatter written in Rust (~35x faster). Replaces the psf/black pre-commit hook, migrates [tool.black] configuration, and removes black from dev dependencies.

When to Use This Skill

Context

• Pre-commit config: !find . -maxdepth 1 -name '.pre-commit-config.yaml'
• pyproject.toml: !find . -maxdepth 1 -name 'pyproject.toml'
• ruff already present: !find . -maxdepth 1 -name 'ruff.toml'

Parameters

Execution

Execute this black-to-ruff-format migration:

Step 1: Audit current black configuration

1. Read .pre-commit-config.yaml and locate psf/black entries.
2. Read pyproject.toml and extract the [tool.black] section.
3. Report findings:

   black → ruff-format migration audit
   =====================================
   pre-commit hook:  psf/black found at rev <rev>
   pyproject.toml:   [tool.black] section found (line-length=<N>, target-version=<X>)
   ruff already:     EXISTS / NOT PRESENT
   

   If --check-only, stop here.

Step 2: Update .pre-commit-config.yaml

Remove the psf/black repo block. If ruff-pre-commit is already present, add the ruff-format hook ID. Otherwise add the full ruff-pre-commit repo block with both ruff and ruff-format hooks:

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.9.1  # use latest stable ruff version
  hooks:
    - id: ruff
      args: [--fix]
    - id: ruff-format

If ruff-pre-commit already exists but only has the ruff linter hook, add the ruff-format hook ID under the same repo block.

Step 3: Migrate [tool.black] → [tool.ruff.format] in pyproject.toml

Convert black configuration to ruff format config:

Remove the [tool.black] section. Merge settings into [tool.ruff] and [tool.ruff.format] sections (create if absent, merge if existing).

Step 4: Remove black from dependencies

Remove black from dev/lint dependencies:

# With uv
uvx --from uv uv remove --dev black 2>/dev/null || true

If not using uv, note it for manual removal.

Step 5: Verify migration

Run the new hook to confirm it works:

pre-commit run ruff-format --all-files

If it exits 0, the migration is complete. If it produces diffs, this is expected on first run (ruff format may reformat some files differently from black). Commit the reformatted files as part of the migration.

Step 6: Report

Print a summary of changes:

black → ruff-format migration complete
=======================================
.pre-commit-config.yaml   UPDATED (removed psf/black, added ruff-format hook)
pyproject.toml            UPDATED ([tool.black] → [tool.ruff.format])

Note: ruff-format is Black-compatible (same defaults), but may reformat a small
number of files. Review the diff and include these reformatted files in the
migration commit.

Files to stage:
  git add .pre-commit-config.yaml pyproject.toml
  git add <any reformatted .py files>

Agentic Optimizations

Quick Reference

See Also

• /migration-patterns:flake8-to-ruff — Migrate flake8/isort linting to ruff
• /migration-patterns:mypy-to-ty — Migrate mypy to ty
• /configure:repo — End-to-end repo config driver