Switch to Ruff: One fast tool to lint, format, and sort imports in Python

Ruff is a single, ultra-fast tool that replaces multiple Python utilities (flake8, isort, parts of pylint) and even includes a built-in formatter. If you want simpler tooling and faster CI, Ruff is the pragmatic upgrade.

Further reading: Ruff official docs, Ruff on GitHub, and a short note from Simon Willison.

Quick start (10 minutes)

• Install: pip install ruff
• Format your code: ruff format
• Lint and auto-fix: ruff check . --fix
• Only sort imports (if rolling out gradually): ruff check . --select I --fix

Best-practice config (pyproject.toml)

Add a minimal pyproject.toml so every developer and CI get the same behavior. Start conservative, then expand as your team aligns on style.

• [tool.ruff] — set line-length (e.g., 100) and optionally extend-exclude for generated folders.
• [tool.ruff.lint] — begin with select = ["E", "F", "I", "UP", "B"] (pycodestyle, pyflakes, import sorting, modernizations, bugbear) and tune ignore to match your codebase (common: E203, E501 if you prefer formatter-driven wrapping).
• [tool.ruff.format] — pick quote-style = "single" or "double" to match team preference.

Pre-commit and CI

• Pre-commit: run ruff check --fix and ruff format locally to prevent noisy diffs.
• GitHub Actions (example): a job step that runs ruff check . --output-format=github can annotate PRs with inline findings.
• Fail-safe rollout: treat formatter as a separate step first; once stable, make linting required in CI.

Safe rollout in legacy repos

• Start with format-only to minimize risk, then add linting rules incrementally.
• Limit scope: run on src/ or a few key packages first.
• Use targeted rules (e.g., --select I for imports, then add E, F, UP).
• Document any per-file-ignores and plan to remove them over time.

Why teams adopt Ruff

• Speed: written in Rust; big repos see dramatic lint/format time drops.
• Simplicity: one tool and one config reduces maintenance overhead.
• Consistency: identical results across machines and CI.

Source: see the Ruff docs for rule coverage, configuration, and migration guidance.

Takeaway

Consolidate Python linting, formatting, and import sorting with Ruff. Start with formatter-only, add core rules, and lock it into pre-commit and CI for durable wins.

Get smarter about AI and dev tools in minutes each week—subscribe to The AI Nuggets newsletter.