Ruff — Fast Python Linter and Formatter Written in Rust

Ruff combines linting and formatting for Python behind a single command-line interface, with the stated aim of being orders of magnitude faster than alternative tools while integrating more functionality. The documentation describes it as 10-100x faster than existing linters such as Flake8 and formatters such as Black. It can replace Flake8 and dozens of its plugins, Black, isort, pydocstyle, pyupgrade and autoflake, among others. Ruff is documented on docs.astral.sh alongside Astral's other projects, uv and ty, and offers an online playground.

• Written in Rust; installable via pip
• 10-100x faster than existing linters and formatters
• Drop-in parity with Flake8, isort and Black
• Built-in caching to avoid re-analysing unchanged files
• Fix support for automatic error correction
• Python 3.14 compatibility
• First-party editor integrations for VS Code and more
• Monorepo-friendly hierarchical and cascading configuration

The Ruff linter is exposed through ruff check, which accepts files or directories, lints all discovered Python files recursively and can optionally fix any fixable errors. Rule codes mirror Flake8's system, with a one-to-three letter prefix indicating the rule's source followed by three digits, and selection is controlled by the lint.select, lint.extend-select and lint.ignore settings. The special ALL code enables every rule, and Ruff automatically disables conflicting pydocstyle rules in that case. Fixes carry a safety classification and can be disabled, and errors can be suppressed at line, block or file level.

• ruff check — lint files in the current directory
• ruff check --fix — fix fixable errors
• ruff check --watch — re-lint on change
• Rule categories include correctness, suspicious, complexity, performance, style, security, formatting and pedantic

Ruff supports over 900 lint rules, many inspired by tools such as Flake8, isort and pyupgrade, with every rule re-implemented in Rust as a first-party feature. By default, Ruff enables rules from the F, E, B, UP and RUF categories plus others, omitting stylistic rules that overlap with the use of a formatter such as ruff format or Black. The rules reference groups entries by originating tool — for example Airflow (AIR), eradicate (ERA), FastAPI (FAST) and flake8-bugbear (B) — and marks each rule's status. Rules may be stable, in preview, deprecated or removed, and those fixable with --fix are flagged.

• Over 900 built-in rules
• Default categories: F, E, B, UP and RUF
• Status markers for preview, deprecated and removed rules
• Automatic fix availability indicated per rule

The Ruff formatter is available through the ruff CLI as ruff format and is designed as a drop-in replacement for Black. Running ruff format on a file or directory formats it in place, while ruff format --check leaves files untouched and exits with a non-zero status code when unformatted files are found. The formatter's stated initial goal is to innovate on performance rather than code style, so it adheres to Black's stable code style; when run over extensive Black-formatted projects such as Django and Zulip, more than 99.9% of lines are formatted identically. It also supports docstring code formatting, including doctests, CommonMark fenced code blocks and reStructuredText literal and code-block directives.

• ruff format — format all files in the current directory
• ruff format --check — detect unformatted files without writing
• Documented intentional deviations and preview style
• Format suppression and documented conflicting lint rules

Ruff can be configured through a pyproject.toml, ruff.toml or .ruff.toml file, and the configuration strategy and semantics are the same whether it is used as a linter, a formatter or both. Configuration files are discovered by locating the closest file for a given path, and a file may be passed directly with the --config flag; argfiles and shell autocompletion are also supported. The default configuration sets line-length = 88 (the same as Black) and indent-width = 4, excludes a list of commonly ignored directories, and mirrors Black's choices for quote style, indent style, magic trailing commas and line endings. The complete list of options is enumerated in the settings reference.

• Configuration files: pyproject.toml, ruff.toml or .ruff.toml
• line-length = 88, indent-width = 4 by default
• exclude and extend-exclude for glob-based file patterns
• cache-dir, defaulting to .ruff_cache and overriding RUFF_CACHE_DIR
• extend to merge a base configuration file
• builtins to treat additional names as defined references

The Ruff Language Server exposes configuration options that customise its behaviour and can also read an existing pyproject.toml or ruff.toml file to configure the linter and formatter. Settings are supplied when the server is initialised; VS Code provides a UI for them, while other editors may require manual configuration. Configuration may be given as a path to a file or, since Ruff 0.9.8, as an inline JSON object. Where several sources are present, individual editor settings take precedence over ruff.configuration, which in turn takes precedence over a project configuration file, with configurationPreference controlling the ordering.

• configuration — file path or inline JSON
• configurationPreference — editorFirst, filesystemFirst or editorOnly
• Other options include exclude, lineLength, fixAll, organizeImports, showSyntaxErrors, logLevel and logFile
• Documented examples for VS Code, Neovim and Zed

The FAQ states that the Ruff linter is compatible with Black out of the box, provided the line-length setting is consistent between the two, and that Ruff defers implementing stylistic rules obviated by automated formatting. One difference is line-length enforcement: Ruff flags line-too-long (E501) for any line exceeding the setting, while Black and ruff format avoid automatic wrapping in some cases such as comments. Ruff can serve as a drop-in replacement for Flake8 when used without or with a small number of plugins, alongside Black, and on Python 3 code; under those conditions it implements every Flake8 rule, covering the F rules from Pyflakes and a subset of the E and W rules from pycodestyle. Many popular Flake8 plugins and related tools, including autoflake, eradicate, flake8-bugbear and flake8-comprehensions, are re-implemented natively.

• Compatible with Black when line-length matches
• Formatter intended as a drop-in replacement for Black
• Drop-in replacement for Flake8 under the stated conditions
• Native re-implementations of popular Flake8 plugins

Ruff uses a custom versioning scheme in which the minor version number carries breaking changes and the patch version number carries bug fixes; semantic versioning and the major version number will be used once Ruff's API is stable. Minor increases occur when, for example, a deprecated option is removed, configuration changes in a backwards-incompatible way, a stable rule's behaviour changes, or support for an end-of-life Python version is dropped. Patch increases cover bug fixes, backwards-compatible new configuration options, support for a new Python version, and preview-stage rule and fix additions. Ruff's crates are published to crates.io, with ruff, ruff_linter and ruff_wasm following the normal versioning policy while the remaining crates are treated as internal and unstable.

• Minor version for breaking changes, patch version for bug fixes
• ruff, ruff_linter and ruff_wasm follow the versioning policy
• Other published crates versioned 0.0.x with no stability guarantees
• Documented preview mode, rule stabilisation and fix stabilisation policies

The contributing guide covers how to work on Ruff, noting that contributions to ty are handled by a separate guide. Issues suitable for newcomers are labelled good first issue and generally do not require significant experience with Rust or the Ruff codebase, while help wanted marks opportunities for subsequent contributions. Contributors do not need permission to start on issues carrying those labels, but are asked to indicate that they are working on one to avoid duplicated effort, and to check in before starting on unlabelled issues. Pull requests for new features without prior discussion, or for issues labelled needs-decision or needs-design, are not accepted, and all use of AI in contributions must follow the project's AI Policy.

• good first issue and help wanted labels for community contributions
• bug-labelled issues are the best other candidates
• No pull requests for needs-decision or needs-design issues
• Documented project structure across crates such as ruff, ruff_linter and ruff_formatter
• Worked examples for adding a lint rule and an auto-fix

Ruff is described as extremely actively developed and is used in major open-source projects. The project page collects testimonials from maintainers of other Python tools and projects, including Sebastián Ramírez of FastAPI, Nick Schrock of Elementl, Bryan Van de Ven of Bokeh, Timothy Crosley of isort and Tim Abbott of Zulip, most of which comment on execution speed.

• Apache Airflow
• Apache Superset
• FastAPI
• Hugging Face
• Pandas
• SciPy