Python Ruff Catches 900 Rules — Lint Setup That Scales

Python linting used to mean assembling a toolchain. Flake8 for errors, Black for formatting, isort for imports, pyupgrade for modernization, plus a plugin for every extra opinion. Each tool parsed your code separately, so a pre-commit run took minutes and configs lived in three files.

Slow feedback kills adoption. When lint takes longer than the test suite, developers skip the hook with --no-verify. You'll recognize the result: PRs full of style nits and real bugs hiding behind them.

Ruff ends the assembly job. One Rust binary runs 900+ rules and a Black-compatible formatter in milliseconds. It reads a single config section and plugs into pre-commit, CI, and VS Code cleanly.

Speed alone won't save you though. Enabling every rule at once buries the team, and mixing two formatters creates phantom diffs. This guide shows the rollout that sticks.

Why Ruff Replaces Four Tools Instead of Joining Them

The classic Python toolchain grew by accretion. Flake8 checks errors, Black formats, isort sorts imports, pyupgrade modernizes syntax — each parses your code independently, each has its own config, and a pre-commit run pays the startup cost four times. On a large repo that means minutes per commit.

Ruff reimplements all of it in Rust behind one interface. Its 900+ rules are native ports of Flake8 plugins (bugbear, pyupgrade, isort, pydocstyle, and more), and its formatter is a Black-compatible fork of the Rome formatter. One parse feeds every check, and a global cache skips unchanged files.

The practical effect is a different development rhythm. Lint-on-save in VS Code answers instantly, pre-commit hooks finish before you context-switch, and CI lint stages stop dominating pipeline time. Speed is not vanity here — it is what makes the checks actually run.

Install Ruff and Baseline Before Changing Anything

Install Ruff with pip, uv, or the standalone installer, then take a baseline before changing anything. ruff check --statistics ranks your current violations by rule so you know what you are adopting. ruff format --check shows how far your style is from the formatter without touching files.

Do not fix anything yet. The baseline tells you which rule families are cheap to enable (usually E and F) and which will need a campaign (often SIM or D). That ordering drives the whole rollout.

pip install "ruff==0.16.6"
ruff --version
ruff check --statistics .
ruff format --check .

Configure Once — pyproject.toml That Survives Review

All Ruff configuration lives in one place: pyproject.toml (or ruff.toml). Set line-length and target-version first — target-version gates every modernization suggestion, so it must match your oldest production interpreter.

The lint section selects rule families: E (errors), F (pyflakes), B (bugbear), UP (pyupgrade), I (isort). Start with that set. Per-file ignores exempt tests from assert rules and migrations from everything. Keep unsafe-fixes off globally and enable it only for deliberate one-shot cleanups.

The format section mirrors Black options. One decision matters most: Ruff format or Black, never both. The example above is a sane production starting point for a Python 3.12 fleet.

[tool.ruff]
line-length = 88
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "B", "UP", "I"]
ignore = ["E501"]
fixable = ["ALL"]
unsafe-fixes = false

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]
"**/migrations/*" = ["ALL"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

check vs format vs fix — The Daily Commands

ruff check reports violations; --fix applies safe autofixes like removing unused imports. Unsafe fixes — things that can change semantics — require explicit opt-in and a human reading the diff. That two-tier design is the whole safety model.

Local workflow: ruff check --fix . then ruff format ., review the diff, commit. CI workflow: bare ruff check . and ruff format --check . with no fix flags, so violations fail the build. Fixing in CI means CI authors code nobody reviews.

--statistics stays useful forever: run it monthly to find the next rule family worth enabling. Each new family is a small PR with an owner, not a big bang.

Pre-commit, VS Code, and CI Wired Together

Two hooks cover everything: ruff-check with --fix for lint autofixes, ruff-format for style. Pin rev to an exact version and bump it monthly with pre-commit autoupdate — unpinned hooks are how phantom diffs sneak in.

Pair the hooks with the first-party VS Code extension for instant feedback while typing. The extension uses the same binary and config, so editor and CI never disagree.

For GitHub Actions, the ruff-action runs the same checks on the whole repo. Keep the local and remote versions identical; version skew between hook and action produces works-here-fails-there confusion.

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.16.6
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

Rolling Out to Legacy Code Without a Revolt

Legacy codebases need a campaign, not a flag day. Week one: E and F with autofix. Week two: B (bugbear catches real bugs). Week three: UP (modernize syntax). Then I (import sorting) and SIM (simplifications), each as a reviewed PR.

Preview rules stay off in production config — they are the unstable frontier where the incident above happened. Revisit them quarterly, never on a Friday.

Track the burn-down with --statistics in a visible place. Watching SIM violations drop from 800 to zero across four weeks keeps the team motivated in a way a single giant PR never does.