# astral-sh/ruff architecture

> Architecture diagram of the GitHub repository astral-sh/ruff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astral-sh/ruff
- Repository: https://github.com/astral-sh/ruff

## Overview

Ruff is a Rust-based Python linter and formatter. A user invokes its CLI to select a check or format operation; the check workflow analyzes Python files with configurable rules, reports diagnostics, and can apply fixes, while formatting rewrites source into a consistent style. The README also documents caching, cascading configuration, stdin use, import sorting parity, and editor integrations. The graph captures those product branches and shared runtime layers; detailed internal wiring is limited because the supplied source excerpts do not include the main command implementations.

Main entry points: [`crates/ruff/src/commands/check.rs`](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/commands/check.rs) (Check command), [`crates/ruff/src/commands/format.rs`](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/commands/format.rs) (Format command), [`crates/ruff/src/main.rs`](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/main.rs) (CLI entry), [`crates/ruff_linter/src/linter.rs`](https://github.com/astral-sh/ruff/blob/main/crates/ruff_linter/src/linter.rs) (Lint engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI entry<br/>[main.rs]"]
  node_check["Check command<br/>[check.rs]"]
  node_stdin["Stdin commands<br/>[stdin.rs]"]
end

subgraph group_analysis["Lint analysis"]
  node_linter["Lint engine<br/>[linter.rs]"]
  node_rules["Rule checks"]
  node_parser["Python parser"]
  node_fixes["Automatic fixes"]
  node_graph["Import graph<br/>[lib.rs]"]
end

subgraph group_formatting["Formatting"]
  node_format["Format command<br/>[format.rs]"]
  node_formatter["Formatter engine<br/>[lib.rs]"]
end

subgraph group_shared["Shared runtime"]
  node_diagnostics["Diagnostics<br/>[diagnostics.rs]"]
  node_printer["Result output<br/>[printer.rs]"]
  node_config["Settings resolution<br/>[resolve.rs]"]
  node_cache[("File cache<br/>[cache.rs]")]
  node_file_system["File access<br/>[system.rs]"]
end

subgraph group_integrations["Integrations"]
  node_server["Editor server<br/>[server.rs]"]
end

node_user(("Developer"))
node_python["Python files"]

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_check
node_cli -->|"dispatches"| node_format
node_user -.->|"connects editor"| node_server
node_python -->|"provides paths"| node_check
node_python -->|"provides paths"| node_format
node_check -->|"resolves settings"| node_config
node_check -->|"reads files"| node_file_system
node_check -->|"uses cache"| node_cache
node_check -->|"runs analysis"| node_linter
node_check -->|"collects results"| node_diagnostics
node_linter -->|"parses source"| node_parser
node_linter -->|"checks rules"| node_rules
node_check -->|"applies fixes"| node_fixes
node_diagnostics -->|"renders results"| node_printer
node_format -->|"resolves settings"| node_config
node_format -->|"reads and writes"| node_file_system
node_format -->|"formats source"| node_formatter
node_check -.->|"analyzes imports"| node_graph

click node_cli "https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/main.rs"
click node_check "https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/commands/check.rs"
click node_stdin "https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/stdin.rs"
click node_server "https://github.com/astral-sh/ruff/blob/main/crates/ruff_server/src/server.rs"
click node_linter "https://github.com/astral-sh/ruff/blob/main/crates/ruff_linter/src/linter.rs"
click node_rules "https://github.com/astral-sh/ruff/tree/main/crates/ruff_linter/src/rules"
click node_parser "https://github.com/astral-sh/ruff/tree/main/crates/ruff_python_parser"
click node_fixes "https://github.com/astral-sh/ruff/tree/main/crates/ruff_linter/src/fix"
click node_diagnostics "https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/diagnostics.rs"
click node_printer "https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/printer.rs"
click node_format "https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/commands/format.rs"
click node_formatter "https://github.com/astral-sh/ruff/blob/main/crates/ruff_formatter/src/lib.rs"
click node_config "https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/resolve.rs"
click node_cache "https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/cache.rs"
click node_file_system "https://github.com/astral-sh/ruff/blob/main/crates/ruff_db/src/system.rs"
click node_graph "https://github.com/astral-sh/ruff/blob/main/crates/ruff_graph/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_check,node_stdin toneBlue
class node_linter,node_rules,node_parser,node_fixes,node_graph toneAmber
class node_format,node_formatter toneMint
class node_diagnostics,node_printer,node_config,node_cache,node_file_system toneRose
class node_server,node_user,node_python toneIndigo
```

## Components

### User interfaces

- [CLI entry](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/main.rs): `crates/ruff/src/main.rs`
- [Check command](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/commands/check.rs): `crates/ruff/src/commands/check.rs`
- [Stdin commands](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/stdin.rs): `crates/ruff/src/stdin.rs`

### Lint analysis

- [Lint engine](https://github.com/astral-sh/ruff/blob/main/crates/ruff_linter/src/linter.rs): `crates/ruff_linter/src/linter.rs`
- [Rule checks](https://github.com/astral-sh/ruff/tree/main/crates/ruff_linter/src/rules): `crates/ruff_linter/src/rules`
- [Python parser](https://github.com/astral-sh/ruff/tree/main/crates/ruff_python_parser): `crates/ruff_python_parser`
- [Automatic fixes](https://github.com/astral-sh/ruff/tree/main/crates/ruff_linter/src/fix): `crates/ruff_linter/src/fix`
- [Import graph](https://github.com/astral-sh/ruff/blob/main/crates/ruff_graph/src/lib.rs): `crates/ruff_graph/src/lib.rs`

### Formatting

- [Format command](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/commands/format.rs): `crates/ruff/src/commands/format.rs`
- [Formatter engine](https://github.com/astral-sh/ruff/blob/main/crates/ruff_formatter/src/lib.rs): `crates/ruff_formatter/src/lib.rs`

### Shared runtime

- [Diagnostics](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/diagnostics.rs): `crates/ruff/src/diagnostics.rs`
- [Result output](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/printer.rs): `crates/ruff/src/printer.rs`
- [Settings resolution](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/resolve.rs): `crates/ruff/src/resolve.rs`
- [File cache](https://github.com/astral-sh/ruff/blob/main/crates/ruff/src/cache.rs): `crates/ruff/src/cache.rs`
- [File access](https://github.com/astral-sh/ruff/blob/main/crates/ruff_db/src/system.rs): `crates/ruff_db/src/system.rs`

### Integrations

- [Editor server](https://github.com/astral-sh/ruff/blob/main/crates/ruff_server/src/server.rs): `crates/ruff_server/src/server.rs`

### Other components

- **Developer**
- **Python files**

## Connections

- Developer → CLI entry: invokes
- CLI entry → Check command: dispatches
- CLI entry → Format command: dispatches
- Developer → Editor server: connects editor
- Python files → Check command: provides paths
- Python files → Format command: provides paths
- Check command → Settings resolution: resolves settings
- Check command → File access: reads files
- Check command → File cache: uses cache
- Check command → Lint engine: runs analysis
- Check command → Diagnostics: collects results
- Lint engine → Python parser: parses source
- Lint engine → Rule checks: checks rules
- Check command → Automatic fixes: applies fixes
- Diagnostics → Result output: renders results
- Format command → Settings resolution: resolves settings
- Format command → File access: reads and writes
- Format command → Formatter engine: formats source
- Check command → Import graph: analyzes imports