astral-sh/ruff

An extremely fast Python linter and code formatter, written in Rust.

46,782 stars Rust 10 components 8 connections

Rust-based Python linter and formatter with 800+ rules

Files are discovered, parsed into ASTs, processed by linting rules or formatters, and output as diagnostics or formatted code

Under the hood, the system uses 2 feedback loops, 3 data pools, 4 control points to manage its runtime behavior.

Structural Verdict

A 10-component dev tool with 8 connections. 4773 files analyzed. Well-connected — clear data flow between components.

How Data Flows Through the System

Files are discovered, parsed into ASTs, processed by linting rules or formatters, and output as diagnostics or formatted code

File Discovery — Scan directories for Python files respecting exclusion patterns
Configuration Resolution — Load and merge pyproject.toml settings for each file's context
Source Parsing — Parse Python source code into AST using ruff_python_parser
Rule Application — Apply 800+ linting rules to AST nodes generating violations
Fix Generation — Generate automatic fixes for violations when possible
Output Formatting — Format diagnostics or apply code formatting based on command

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

File Cache (cache)
Stores file modification times and linting results to skip unchanged files

Configuration Cache (cache)
Caches resolved pyproject.toml configurations per directory

AST Cache (in-memory)
Parsed AST nodes for processed files

Feedback Loops

Watch Mode (polling, balancing) — Trigger: File system events. Action: Re-lint changed files. Exit: User termination.
Cache Validation (cache-invalidation, balancing) — Trigger: File modification time change. Action: Re-parse and re-lint file. Exit: File unchanged.

Delays & Async Processing

Parallel Processing (async-processing, ~Variable based on file count) — Files processed in parallel batches
Cache Write (async-processing, ~Per-file basis) — Cache updates written after linting completes

Control Points

Rule Selection (env-var) — Controls: Which linting rules are enabled/disabled
Fix Mode (runtime-toggle) — Controls: Whether to apply automatic fixes
Output Format (runtime-toggle) — Controls: How diagnostics are formatted (text, json, etc.)
Cache Enable (feature-flag) — Controls: Whether file caching is used

Technology Stack

Rust (framework)
Core implementation language

clap (library)
CLI argument parsing

rayon (library)
Parallel processing

serde (library)
Configuration serialization

toml (library)
Configuration file parsing

rustc-hash (library)
Fast hashing for performance

anyhow (library)
Error handling

log (library)
Logging

ignore (library)
File filtering and exclusion patterns

tempfile (library)
Temporary file handling for caching

Key Components

run (function) — Main entry point that dispatches to different subcommands based on parsed CLI arguments crates/ruff/src/lib.rs
Args (type-def) — Complete CLI argument structure with all subcommands and global options crates/ruff/src/args.rs
check (function) — Main linting function that processes files, applies rules, and generates diagnostics crates/ruff/src/commands/check.rs
format (function) — Main formatting function that applies Python code formatting with configurable options crates/ruff/src/commands/format.rs
project_files_in_path (function) — Discovers Python files in given paths while respecting exclusion patterns and configuration crates/ruff_workspace/
Resolver (class) — Resolves configuration files and settings for each file in the workspace hierarchy crates/ruff_workspace/
Cache (class) — File-based caching system to avoid re-linting unchanged files crates/ruff/src/cache.rs
Diagnostics (class) — Aggregates and manages linting diagnostics with support for fixes and output formatting crates/ruff/src/diagnostics.rs
Rule (type-def) — Enum representing all 800+ linting rules with their metadata and implementations crates/ruff_linter/
SourceKind (type-def) — Represents different source file types (Python, Jupyter notebooks, etc.) for unified processing crates/ruff_linter/

Sub-Modules

Language Server (independence: medium)
Provides LSP server for real-time editor integration with linting and formatting

Web Assembly (independence: high)
WASM bindings for running Ruff in browser environments like the playground

Python Type System (independence: high)
Experimental type checker and inference engine (ty_* crates)

Configuration

mkdocs.template.yml (yaml)

site_name (string, unknown) — default: Ruff
theme.name (string, unknown) — default: material
theme.logo (string, unknown) — default: assets/bolt.svg
theme.favicon (string, unknown) — default: assets/favicon.ico
theme.features (array, unknown) — default: navigation.instant,navigation.instant.prefetch,navigation.tracking,content.code.annotate,toc.integrate,toc.follow,navigation.path,navigation.top,content.code.copy,content.tabs.link
theme.palette (array, unknown) — default: [object Object],[object Object],[object Object]
theme.custom_dir (string, unknown) — default: docs/.overrides
repo_url (string, unknown) — default: https://github.com/astral-sh/ruff
+16 more parameters

mkdocs.yml (yaml)

INHERIT (string, unknown) — default: mkdocs.generated.yml
watch (array, unknown) — default: mkdocs.generated.yml

crates/ruff_linter/resources/test/fixtures/fastapi/FAST001.py (python-pydantic)

name (str, unknown)

crates/ruff_linter/resources/test/fixtures/fastapi/FAST003.py (python-pydantic)

my_id (int, unknown)

Explore the interactive analysis

See the full architecture map, data flow, and code patterns visualization.

Analyze on CodeSea

Related Dev Tool Repositories

Frequently Asked Questions

What is ruff used for?

Rust-based Python linter and formatter with 800+ rules astral-sh/ruff is a 10-component dev tool written in Rust. Well-connected — clear data flow between components. The codebase contains 4773 files.

How is ruff architected?

ruff is organized into 5 architecture layers: CLI Interface, Python Language Processing, Linter Engine, Formatter Engine, and 1 more. Well-connected — clear data flow between components. This layered structure enables tight integration between components.

How does data flow through ruff?

Data moves through 6 stages: File Discovery → Configuration Resolution → Source Parsing → Rule Application → Fix Generation → .... Files are discovered, parsed into ASTs, processed by linting rules or formatters, and output as diagnostics or formatted code This pipeline design reflects a complex multi-stage processing system.

What technologies does ruff use?

The core stack includes Rust (Core implementation language), clap (CLI argument parsing), rayon (Parallel processing), serde (Configuration serialization), toml (Configuration file parsing), rustc-hash (Fast hashing for performance), and 4 more. This broad technology surface reflects a mature project with many integration points.

What system dynamics does ruff have?

ruff exhibits 3 data pools (File Cache, Configuration Cache), 2 feedback loops, 4 control points, 2 delays. The feedback loops handle polling and cache-invalidation. These runtime behaviors shape how the system responds to load, failures, and configuration changes.

What design patterns does ruff use?

5 design patterns detected: Workspace Architecture, Rule Implementation, Configuration Cascade, Error Tolerance, Parallel Processing.

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.