Ruff: A Rust-powered Python linter and formatter
A Rust-written Python linter and formatter that combines Flake8, Black, and isort with much higher speed.
GitHub astral-sh/ruff Updated 2026-11-07 Branch main Stars 50.7K Forks 2.6K
Rust Python pyproject.toml Flake8 Black VS Code

🧭 Decision Guide

Try it if you

  • You maintain a Python project currently using Flake8, Black, and isort.
    The README explicitly lists Flake8, Black, and isort as replaceable tools and claims drop-in parity.
  • Your monorepo needs pyproject.toml, hierarchical configuration, and caching to reduce repeated analysis.
    The README lists pyproject.toml support, hierarchical and cascading configuration, and built-in caching.
  • You want to integrate checks into VS Code, pre-commit, or GitHub Actions.
    The README Usage section documents integrations for VS Code, ruff-pre-commit, and ruff-action.

Skip it if you

  • Your target code is not Python, or you do not need Python 3.15 compatibility and Python linting.
    The core description defines Ruff as a Python linter and code formatter, and the README's commands target Python files.
  • You must verify the behavior of every existing Flake8 plugin, but the provided material has no itemized compatibility details.
    The README mentions native re-implementations such as flake8-bugbear but provides no complete plugin compatibility matrix.

Requirements

  • Ruff can be installed with pip: `pip install ruff`.
  • The README provides Python 3.15 compatibility but does not state a minimum Python version.
  • A specific version can be run directly with `uvx [email protected]`.
  • For GitHub Actions integration, the README example uses `ubuntu-latest` and `astral-sh/ruff-action@v3`.

First step (verbatim from README)

uvx [email protected] check   # Lint all files in the current directory.

Watch out

  • Using `--fix` modifies code automatically, including removing unused imports.
    The README explicitly lists Fix support and gives automatically removing unused imports as an example.
  • Pinned integrations must stay synchronized with 0.17.4; the pre-commit example uses `rev: v0.17.4`.
    Both the README installation commands and pre-commit example use 0.17.4.
  • The README's speed figures come from claims and testimonials and should not be treated as 10–100x for every project.
    The README includes the 10–100x claim, a 0.4-second Dagster 250k LOC example, and Bokeh's approximately 150–200x testimonial.

Alternatives

  • Flake8:Flake8 is more direct when the project must retain its existing Flake8 configuration or plugin chain.
    README
  • Black:Black is more focused when the team only needs Black's formatting responsibility without Ruff's linting and rule set.
    README
  • isort:isort is a closer fit when the workflow requires only an independent import-sorting tool.
    README

Not stated in the README

  • The README does not provide Ruff's minimum supported Python version.
  • The README does not specify the hardware, code size, or benchmarking method behind the 10–100x claim.
  • The README does not provide a complete compatibility matrix for Flake8 plugins.
  • The omitted Configuration and Rules sections do not provide concrete configuration keys or rule-enablement details in the supplied material.
  • The material does not state whether migration from Flake8, Black, or isort causes behavioral differences or provides configuration-conversion tools.

💡 Deep Analysis

6
Yes I currently maintain Flake8 and its plugins, isort, Black, pydocstyle, pyupgrade, and autoflake. Can Ruff unify linting, formatting, and some automatic fixes for this project?
For: An engineer maintaining a Python project that currently uses Flake8, isort, Black, pydocstyle, pyupgrade, and autoflake, and wants to reduce toolchain maintenance

Yes, because Ruff explicitly consolidates most of these Python tools behind one Rust-native executable and one common interface.

  • The README says Ruff can replace Flake8, including dozens of plugins, as well as Black, isort, pydocstyle, pyupgrade, and autoflake.
  • It provides more than 900 built-in rules and native reimplementations of popular Flake8 plugins, including flake8-bugbear.
  • ruff check performs linting and supports automatic fixes, such as removing unused imports; ruff format provides formatting.
  • The README also targets drop-in parity with Flake8, isort, and Black, but that does not prove identical behavior for every plugin edge case, so existing CI results still need to be compared during migration.
  • README: "Ruff can be used to replace Flake8 (plus dozens of plugins), Black, isort, pydocstyle, pyupgrade, autoflake, and more"
  • README: "Over 900 built-in rules"
  • README: "Fix support, for automatic error correction (e.g., automatically remove unused imports)"
  • README: "Drop-in parity with Flake8, isort, and Black"
pip install ruff
Not stated in the README:The README does not list every third-party Flake8 plugin currently used by the project or its coverage.;The README does not provide a rule-by-rule mapping from the existing configuration to Ruff.
Yes I need VS Code, local pre-commit, and GitHub Actions to use the same Python linting and formatting workflow. Can Ruff cover all three entry points?
For: An engineer who wants one Python checking workflow across VS Code, pre-commit, and GitHub Actions

Yes, because the README provides first-party or official integration examples for VS Code, pre-commit, and GitHub Actions.

  • It explicitly provides a VS Code extension and links to setup instructions for other editors.
  • The ruff-pre-commit example configures both ruff-check and ruff-format; the lint hook can receive --fix.
  • The GitHub Actions example uses astral-sh/ruff-action@v3 and runs on both push and pull_request events.
  • These entry points share Ruff’s check and format commands, but the README does not state whether VS Code, hooks, and CI automatically use identical working directories, versions, or configuration. The pre-commit version shown must also be coordinated with the CI version policy.
  • README: "First-party editor integrations for VS Code and more"
  • README `ruff-pre-commit` example includes `ruff-check` and `ruff-format`
  • README GitHub Actions example uses `astral-sh/ruff-action@v3`
  • README GitHub Actions example runs on `push` and `pull_request`
pipx install ruff
Not stated in the README:The README does not explain how the VS Code extension handles multiple nested `pyproject.toml` configurations.;The README does not describe behavior when the local Ruff version, pre-commit revision, and GitHub Action version differ.
Yes I maintain a large Python codebase such as Apache Airflow, Pandas, or SciPy, and both pre-commit and CI require fast feedback. Is Ruff worth replacing the existing linters?
For: An engineer maintaining a large Python codebase such as Apache Airflow, Apache Superset, FastAPI, Hugging Face, Pandas, or SciPy

Yes, especially when large-repository checks must run in pre-commit, editors, and CI, because the README presents speed, caching, and repository-scale configuration as first-class capabilities.

  • Ruff is written in Rust, and the README claims it is 10–100 times faster than tools such as Flake8 and Black.
  • Built-in caching avoids re-analyzing unchanged files, which supports incremental checks.
  • The README explicitly calls Ruff Monorepo-friendly and documents hierarchical, cascading configuration; its commands also recurse through the current directory and subdirectories.
  • It provides ruff-pre-commit, VS Code, and other editor integrations, and lists Apache Airflow, Pandas, and SciPy among its users. However, the README does not provide repository sizes, measured runtimes, or actual CI savings for those projects.
  • README: "10-100x faster than existing linters (like Flake8) and formatters (like Black)"
  • README: "Built-in caching, to avoid re-analyzing unchanged files"
  • README: "Monorepo-friendly, with hierarchical and cascading configuration"
  • README user list includes Apache Airflow, Pandas, and SciPy
uvx [email protected] check   # Lint all files in the current directory.
Not stated in the README:The README does not provide the target repository's file count, current lint duration, or measured post-migration performance.;The README does not say whether the existing CI depends on project-specific checks that Ruff does not cover.
Yes My project targets Python 3.15, and I want linting, automatic fixes, and formatting in one tool. Can Ruff serve as the primary Python quality tool?
For: A Python project maintainer who needs Python 3.15 support and wants both formatting and linting

Yes, it is suitable as the primary Python style and linting tool, but it cannot by itself cover type checking, tests, security scanning, or business-semantic analysis.

  • The README explicitly states Python 3.15 compatibility, meeting the stated interpreter target.
  • ruff check performs linting and supports automatic fixes; the README gives removing unused imports as an example.
  • ruff format can format the current directory recursively or operate on a path or .py files.
  • Ruff is positioned as a linter and formatter rather than a complete program-verification platform. The README does not claim to replace type checkers, test frameworks, or security tools, so those capabilities must be handled separately.
  • README: "Python 3.15 compatibility"
  • README: `ruff check` is used for linting
  • README: `ruff format` formats the current directory, paths, or `.py` files
  • Project description: "An extremely fast Python linter and code formatter, written in Rust."
uvx [email protected] format  # Format all files in the current directory.
Not stated in the README:The README does not specify the exact Python 3.15 support boundary for every one of the 900-plus rules.;The README does not describe integration with the project's existing type checker, test framework, or security scanner.
Yes My Monorepo contains multiple Python subprojects, and different directories need to inherit or override different rules. Can Ruff's configuration discovery and cascading model satisfy this constraint?
For: An engineer maintaining a Monorepo with multiple Python subprojects and different rules by directory

Yes, because Ruff explicitly supports hierarchical and cascading configuration for Monorepos, although the exact inheritance behavior still needs to be checked against the repository layout.

  • The README labels Ruff “Monorepo-friendly” and links to configuration-file discovery documentation.
  • pyproject.toml is a documented project configuration entry point for centralizing rules, formatting, and the target Python version.
  • The commands can recursively check the current directory and all subdirectories, while also accepting explicit paths, .py globs, or an argument file.
  • This covers multi-directory execution and configuration inheritance, but the provided README excerpt does not show precedence when parent and child configurations conflict, nor whether each subproject must run Ruff separately.
  • README: "Monorepo-friendly, with hierarchical and cascading configuration"
  • README: "pyproject.toml support"
  • README: "Lint all files in the current directory (and any subdirectories)"
  • README usage examples for `ruff check path/to/code/` and `ruff check @arguments.txt`
ruff check path/to/code/
Not stated in the README:The provided README excerpt does not specify the exact precedence, merge rules, or override syntax for nested configuration files.;The README does not specify the recommended organization for shared and independent configurations across a Monorepo.
It depends My Python project depends on specific third-party Flake8 plugins, and CI must produce exactly the same results as before. Can I directly replace the entire checking chain with Ruff?
For: A Python project maintainer who depends on specific third-party Flake8 plugins and requires exact parity with the existing CI results

It depends, because Ruff covers many common rules, but the README’s compatibility claims do not guarantee identical behavior for every third-party plugin and edge case.

  • Ruff natively reimplements rules from popular Flake8 plugins and provides more than 900 built-in rules, indicating broad coverage for common migrations.
  • The README claims drop-in parity with Flake8, isort, and Black, but it does not promise coverage of every third-party plugin, plugin-version combination, or project-specific check.
  • Ruff aims to consolidate functionality behind one interface, not to make every diagnostic code, default behavior, and fix result identical to the legacy tools.
  • Therefore, direct replacement is not suitable when exact parity is a hard requirement. If the plugins are within Ruff’s implemented scope, migration may work, but coverage must be checked against the current configuration.
  • README: "Over 900 built-in rules, with native re-implementations of popular Flake8 plugins, like flake8-bugbear"
  • README: "Drop-in parity with Flake8, isort, and Black"
  • README: "Ruff aims to be orders of magnitude faster than alternative tools while integrating more functionality behind a single, common interface"
  • Project insight: Ruff is not necessarily fully equivalent to Flake8, isort, and Black in all edge cases, plugin behaviors, and version combinations
ruff check
Not stated in the README:The README does not list whether every specific Flake8 plugin used by the target project has a Ruff equivalent.;The README does not define whether “drop-in parity” covers diagnostic codes, defaults, fix behavior, and version ranges.;The README does not describe an automated method for comparing complete CI output between the legacy tools and Ruff.

✨ Highlights

  • The README claims 10–100x higher speed than Flake8 and Black
  • Includes over 900 built-in rules and can automatically fix unused imports
  • One Rust tool covers Flake8, Black, and isort workflows

🔧 Engineering

  • ruff check lints Python files, while ruff format standardizes code formatting
  • Supports installation through pip, uv, pipx, Homebrew, and Conda
  • Supports monorepos through pyproject.toml and hierarchical configuration
  • Provides VS Code, pre-commit, and GitHub Action integrations

⚠️ Risks

  • The README omits the Configuration and Rules sections, so migration details cannot be confirmed
  • The 10–100x performance figure is a README claim without benchmark conditions or methodology
  • The README does not specify compatibility boundaries for individual Flake8 plugins

👥 For who?

  • Teams maintaining Python projects that use Flake8, Black, or isort
  • Developers needing checks in VS Code, pre-commit, or GitHub Actions
  • Teams maintaining large codebases such as Apache Airflow, FastAPI, or Pandas