Flake8 To Ruff

/migration-patterns:flake8-to-ruff

Migrate from flake8 and/or isort to ruff — consolidating linting and import sorting into a single, fast Rust-based tool. Replaces pre-commit hooks, migrates rule configuration, and removes old 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'
• setup.cfg: !find . -maxdepth 1 -name 'setup.cfg'
• .flake8: !find . -maxdepth 1 -name '.flake8'
• ruff already present: !find . -maxdepth 1 -name 'ruff.toml'

Parameters

Execution

Execute this flake8/isort-to-ruff migration:

Step 1: Audit current configuration

1. Read .pre-commit-config.yaml and locate pycqa/flake8, PyCQA/isort, and pycqa/pep8-naming entries.
2. Read all config sources: pyproject.toml ([tool.flake8], [tool.isort]), setup.cfg ([flake8], [isort]), .flake8.
3. Report findings:

   flake8/isort → ruff migration audit
   =====================================
   pre-commit hooks:  pycqa/flake8 v<rev>, PyCQA/isort v<rev>
   flake8 config:     [tool.flake8] max-line-length=<N>, extend-ignore=[E501,W503], per-file-ignores=<...>
   isort config:      [tool.isort] profile=black, known-first-party=[...]
   ruff already:      EXISTS / NOT PRESENT
   

   If --check-only, stop here.

Step 2: Build ruff rule selection

Map flake8 plugins and ignore rules to ruff equivalents:

For isort config:

Baseline ruff rule selection (add to existing if present):

[tool.ruff.lint]
select = ["E", "W", "F", "I", "N", "B"]
# E/W = pycodestyle, F = pyflakes, I = isort, N = pep8-naming, B = bugbear

Preserve any existing ignores from flake8 config.

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

Remove pycqa/flake8, PyCQA/isort, and any flake8 plugin repos. Add or extend the ruff pre-commit block:

- 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  # include if also migrating from black

Step 4: Update pyproject.toml

1. Remove [tool.flake8] and [tool.isort] sections.
2. Add/merge [tool.ruff], [tool.ruff.lint], and [tool.ruff.lint.isort] sections with converted config.
3. Remove flake8* and isort from dev/lint dependencies:

   uvx --from uv uv remove --dev flake8 isort 2>/dev/null || true
   

Step 5: Remove other config files

If standalone config files exist, delete them:

• .flake8 → delete (config is now in pyproject.toml)
• setup.cfg [flake8]/[isort] sections → remove those sections

Step 6: Verify migration

Run the new hook to confirm it works:

pre-commit run ruff --all-files

Note any new lint errors introduced by ruff's stricter defaults. Decide whether to:

• Fix them immediately
• Add temporary ignore rules in [tool.ruff.lint] ignore
• Accept them as a follow-up

Step 7: Report

Print a summary:

flake8/isort → ruff migration complete
========================================
.pre-commit-config.yaml   UPDATED (removed flake8/isort hooks, added ruff hook)
pyproject.toml            UPDATED ([tool.flake8]+[tool.isort] → [tool.ruff.lint])
.flake8                   DELETED / NOT FOUND
setup.cfg                 UPDATED (removed [flake8]/[isort] sections) / NOT FOUND

Note: Ruff may surface new lint errors not caught by flake8. Review with:
  uvx ruff check . --select E,W,F,I,N,B

Files to stage:
  git add .pre-commit-config.yaml pyproject.toml .flake8 setup.cfg

Agentic Optimizations

Quick Reference

See Also

• /migration-patterns:black-to-ruff-format — Migrate black to ruff format
• /migration-patterns:mypy-to-ty — Migrate mypy to ty
• /configure:repo — End-to-end repo config driver