laurigates/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

| Use this skill when... | Keep flake8/isort when... | |------------------------|--------------------------| | .pre-commit-config.yaml contains pycqa/flake8 or PyCQA/isort | You rely on a flake8 plugin with no ruff equivalent | | [tool.flake8] or [tool.isort] config exists | Team uses flake8 API in custom scripts | | Looking to consolidate linting tooling | CI requires specific flake8 exit codes | | Using ruff format and wanting a unified tool | |

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

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

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:

| flake8 config | ruff equivalent | |---------------|----------------| | max-line-length = N | [tool.ruff] line-length = N | | extend-ignore = E501 | [tool.ruff.lint] ignore = ["E501"] | | per-file-ignores = path:E501 | [tool.ruff.lint.per-file-ignores] "path" = ["E501"] | | pep8-naming plugin | add "N" to select | | flake8-bugbear plugin | add "B" to select | | flake8-annotations plugin | add "ANN" to select |

For isort config:

| isort config | ruff equivalent | |--------------|----------------| | profile = black | [tool.ruff.lint.isort] force-single-line = false | | known-first-party = [...] | [tool.ruff.lint.isort] known-first-party = [...] | | multi-line-output = 3 | Handled by ruff's Black-compatible default | | force-sort-within-sections | [tool.ruff.lint.isort] force-sort-within-sections = true |

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

| Context | Command | |---------|---------| | Audit only | /migration-patterns:flake8-to-ruff --check-only | | Apply migration | /migration-patterns:flake8-to-ruff --fix | | Verify after migration | pre-commit run ruff --all-files | | Check with specific rules | uvx ruff check . --select E,W,F,I |

Quick Reference

| Item | Value | |------|-------| | ruff rule docs | https://docs.astral.sh/ruff/rules/ | | isort equivalent | select "I" in ruff | | pep8-naming equivalent | select "N" in ruff | | Config section | [tool.ruff.lint] and [tool.ruff.lint.isort] |

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