laurigates/black-to-ruff-format

/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

| Use this skill when... | Keep black when... | |------------------------|-------------------| | .pre-commit-config.yaml contains psf/black | Team has strong preference for black's exact output | | [tool.black] exists in pyproject.toml | CI uses black --check specifically by name | | Repo already uses ruff for linting | Project uses black's API in build scripts | | Wanting to consolidate formatting under ruff | |

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

| Parameter | Description | |-----------|-------------| | --check-only | Report what would change without modifying files | | --fix | Apply migration automatically |

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:

| black key | ruff equivalent | Notes | |-----------|----------------|-------| | line-length | [tool.ruff] line-length | Shared with linter | | target-version | [tool.ruff] target-version | Shared with linter | | skip-string-normalization | [tool.ruff.format] quote-style = "preserve" | | | skip-magic-trailing-comma | [tool.ruff.format] skip-magic-trailing-comma = true | | | preview | [tool.ruff.format] preview = true | |

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

| Context | Command | |---------|---------| | Audit only | /migration-patterns:black-to-ruff-format --check-only | | Apply migration | /migration-patterns:black-to-ruff-format --fix | | Verify after migration | pre-commit run ruff-format --all-files | | Check format directly | uvx ruff format --check . |

Quick Reference

| Item | Value | |------|-------| | ruff format docs | https://docs.astral.sh/ruff/formatter/ | | Black compatibility | ruff format is designed as a Black drop-in with ~99.9% compatible output | | Config section | [tool.ruff.format] in pyproject.toml | | Pre-commit hook | ruff-format in astral-sh/ruff-pre-commit |

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