Flake8 and Ruff: Drop-in Replacement Compatibility

The Ruff Linter is described in Astral's documentation as an extremely fast Python linter designed as a drop-in replacement for Flake8 plus dozens of plugins, as well as isort, pydocstyle, pyupgrade and autoflake. Ruff's landing page lists drop-in parity with Flake8, isort and Black among its features, and states it is 10-100x faster than existing linters such as Flake8. The Astral site's Ruff page repeats that Ruff maintains drop-in compatibility with Flake8, isort and more.

• Drop-in replacement for Flake8 plus dozens of plugins
• Drop-in parity with Flake8, isort and Black
• Positioned as 10-100x faster than existing linters

The Ruff FAQ sets out when Ruff can serve as a drop-in replacement for Flake8: when used without or with a small number of plugins, alongside Black, and on Python 3 code. Under those conditions, Ruff implements every rule in Flake8. In practice that means all of the F rules, which originate from Pyflakes, together with a subset of the E and W rules, which originate from pycodestyle.

• Used without or with a small number of plugins
• Used alongside Black
• Applied to Python 3 code
• All F (Pyflakes) rules implemented
• A subset of E and W (pycodestyle) rules implemented

Ruff's linter mirrors Flake8's rule code system, in which each rule code consists of a one-to-three letter prefix followed by three digits, such as F401. The prefix indicates the source of the rule, for example F for Pyflakes, E for pycodestyle and ANN for flake8-annotations. Ruff supports over 900 lint rules, many inspired by tools including Flake8, isort and pyupgrade, and re-implements every rule in Rust as a first-party feature. The FAQ lists Flake8 plugins re-implemented natively, including flake8-2020, flake8-annotations, flake8-async, flake8-bandit, flake8-blind-except, flake8-boolean-trap, flake8-bugbear and flake8-builtins.

• Rule codes follow Flake8's prefix-plus-three-digits format
• Over 900 built-in lint rules
• Rules re-implemented in Rust as first-party features
• Native re-implementations of popular Flake8 plugins such as flake8-bugbear

Ruff's documentation states that it can be used to replace Flake8 and dozens of its plugins, along with Black, isort, pydocstyle, pyupgrade and autoflake, behind a single common interface. The Astral marketing page frames this as replacing dozens of dependencies with a single tool. Ruff also offers an autofix model that can upgrade to newer Python syntax, organise imports and remove unused variables.

• Flake8 and its plugin ecosystem
• Black (via the Ruff formatter)
• isort for import sorting
• pydocstyle, pyupgrade and autoflake

Ruff is configured through a pyproject.toml, ruff.toml or .ruff.toml file, with the same configuration strategy for linting and formatting. Rule selection uses the lint.select, lint.extend-select and lint.ignore settings, which accept either a full rule code such as F401 or any valid prefix such as F. The documentation recommends starting with a small set of rules, for example select = ["E", "F"], and adding groups one at a time, such as "B" to enable the flake8-bugbear rules. A full enumeration of options is published on the Settings page.

• Configuration via pyproject.toml, ruff.toml or .ruff.toml
• Rule selectors accept full codes or prefixes
• ALL selector enables all rules, with conflicting pydocstyle rules disabled automatically
• Editor configuration available through the Ruff Language Server

The FAQ notes a behavioural difference relevant to projects moving from Flake8 and Black. Ruff's linter is compatible with Black out of the box provided the line-length setting is consistent between the two. Black and Ruff's formatter make a best-effort attempt to adhere to the line length but avoid automatic wrapping in some cases, such as within comments, whereas Ruff's linter flags line-too-long (E501) for any line exceeding the setting.