Ruff

Ruff is a Python linter and formatter written in Rust by Astral, built to be 10-100x faster than the tools it replaces. It re-implements the rule sets of Flake8 and its most popular plugins (bugbear, comprehensions, simplify, pydocstyle, pyupgrade, and more) natively, rather than wrapping the originals, and pairs that with a Black-compatible formatter and isort-compatible import sorting, all behind one CLI and one configuration file.

Beyond the CLI, Ruff ships an LSP server (ruff_server) that powers a first-party VS Code extension and other editor integrations, a WASM build behind the public play.ruff.rs playground, and official GitHub Action and pre-commit hook packaging for CI. It’s used in production by large open-source projects including Apache Airflow, Apache Superset, FastAPI, Hugging Face Transformers, pandas, and SciPy, and is developed by Astral, the company behind the uv Python package manager and the ty type checker.

What You Get

• A single ruff binary that lints and formats Python, installable via pip, uvx, pipx, Homebrew, Conda, or a standalone install script.
• Native re-implementations of 900+ rules spanning Flake8’s plugin ecosystem, Black-compatible formatting, and isort-style import sorting.
• An LSP server and first-party VS Code extension for real-time in-editor diagnostics and format-on-save.
• A GitHub Action, pre-commit hook, and Docker image for dropping Ruff into existing CI pipelines.
• Hierarchical pyproject.toml/ruff.toml configuration discovery suited to monorepos.

Common Use Cases

• Migrating an existing Flake8 + Black + isort setup to a single, much faster tool.
• Enforcing consistent Python style and catching bugs in CI before merge.
• Auto-fixing lint violations across large codebases in one pass with --fix.
• Powering real-time lint and format feedback in editors via the LSP server.
• Linting large, actively-changing codebases where tool speed materially affects iteration time.

Under The Hood

Architecture

Ruff is organized as a Rust workspace of dozens of crates under crates/, cleanly separating concerns: crates/ruff owns the CLI entry point (main.rs/lib.rs), argument parsing via clap (args.rs), configuration resolution (resolve.rs), the file-watch cache (cache.rs), and command dispatch (commands/); the linting logic lives in ruff_linter, which orchestrates per-file checkers (src/checkers) across rule families (src/rules, one directory per plugin family such as pyflakes, pycodestyle, pyupgrade); ruff_python_parser produces an AST consumed by ruff_python_ast and ruff_python_semantic (scope resolution / semantic model), which downstream rules query rather than re-implementing traversal themselves; ruff_python_formatter is a separate crate implementing the Black-compatible formatter over the same AST, sharing ruff_python_trivia/ruff_text_size for whitespace and range bookkeeping; ruff_server implements an LSP server reusing the linter/formatter crates directly, and ruff_workspace resolves pyproject.toml/ruff.toml settings into a merged Settings struct threaded through the pipeline. It’s a modular, layered design where the CLI, LSP server, and WASM playground all sit on the same core parser/semantic/linter/formatter crates.

Tech Stack

Ruff is written in Rust (per rust-toolchain.toml) and distributed to Python via maturin with bindings = "bin" — the wheel bundles the compiled binary rather than exposing PyO3 bindings, and the Python-facing python/ruff package is a thin binary locator. CLI parsing uses clap; glob/globset/globwalk/ignore power file discovery; notify implements filesystem watching for --watch; rayon parallelizes per-file linting; and jemalloc/mimalloc are swapped in as global allocators per platform. Python source is parsed by the project’s own ruff_python_parser rather than an external dependency, configuration is deserialized via serde/pyproject-toml, and libcst-style concrete-syntax-tree handling backs certain rewrites. Build and release tooling spans GitHub Actions workflows for cross-platform binary builds, Docker images, a wasm-pack WASM build for the browser playground, and PyPI/crates.io publishing; docs are built with mkdocs-material.

Code Quality

Testing is extensive: thousands of .snap snapshot files under crates/ruff_linter/src/rules and ruff_python_formatter/tests use the insta snapshot-testing crate (visible directly in crates/ruff_linter/src/test.rs’s insta::assert_snapshot! calls), paired with fixture Python files under resources/test/fixtures for a golden-file testing approach per lint rule, run via cargo nextest in CI. Error handling favors anyhow for CLI-level context-chained errors (main.rs’s report_error walks the error chain, special-casing broken-pipe IO errors) and typed Diagnostic/Severity types for lint-level errors, avoiding silent failure. The project dogfoods itself heavily — its own pyproject.toml runs an extensive custom [tool.ruff.lint] rule selection, and clippy.toml gates the Rust side. CI (.github/workflows/ci.yaml) runs formatting, linting, and test jobs gated behind a change-detection job to skip unaffected work, with additional typing and ecosystem-compatibility jobs layered on top of the base test suite.

API Design Ruff’s primary interface is its CLI (ruff check, ruff format), and its ergonomics show throughout: sane Black-compatible defaults out of the box, drop-in rule-name compatibility with Flake8/pyflakes/pycodestyle/isort so migration needs minimal reconfiguration, an all-in-one --fix autofix pathway, and hierarchical pyproject.toml discovery for monorepos. First-party editor integrations (VS Code extension, LSP server) and a GitHub Action reduce onboarding friction close to zero, while a published JSON schema (ruff.schema.json) enables editor autocompletion of configuration and an extensive rule-documentation site makes the 900+ rule surface discoverable without reading source. Replacing a dozen separately-configured tools with one coherent binary and configuration surface is itself the core developer-experience win.