Ruff — fast Python linter and formatter
Ruff reads your code and reports style issues and likely errors very quickly, with options for safe automatic fixes. It is fast enough to be used as an editor save hook, a pre-commit check or a CI step without introducing noticeable delay.

In two words first
Think of Ruff as a proofreader for your Python source: it scans for incorrect or suspicious constructions, unused code, and style inconsistencies before they reach CI or a code review. In practice that means you get immediate, actionable diagnostics during development instead of waiting for a pipeline to catch them. A "linter" is a tool that flags mistakes, potential bugs and rule violations in source code; a "formatter" rewrites code to a consistent style so everyone on a team shares the same layout. "CI" means continuous integration—the automated pipelines that run tests and checks when code is pushed. "Preview rules" are rule families that exist in the tool but are not enabled by default; you must opt in to have them checked.
Ruff aims to make linting non-disruptive by being fast and comprehensive. Because it is implemented in Rust and shipped as a single executable, it avoids Python startup overhead and the multi-process glue of older toolchains. The design goal is simple: lint and format so quickly you can run them on every save, in pre-commit hooks and in CI without the friction that has kept teams from running linters often.
What it does
Ruff combines linting and formatting in one fast command-line program. As a linter it finds syntax issues, unused imports, assigned-but-unused variables, and a wide range of style and correctness issues that were historically covered by a collection of tools such as flake8, pyflakes, pycodestyle and isort. As a formatter it can rewrite source to a common style, similar in intent to tools like black but integrated into the same executable.
A key property is machine-friendly output: Ruff can emit JSON suitable for automated pipelines and editor integrations. That makes it easy to fail a CI job, convert results into an IDE's diagnostics, or aggregate reports. It exposes commands to list available rules, to dump configuration, and it ships a language server so editors can show live diagnostics while you type.
Performance is the central selling point. Implemented in Rust and optimized for throughput, Ruff completes checks far faster than many Python-native linters. This speed enables workflows where linting happens continuously rather than only as a nightly or CI-only step. In addition, Ruff supplies a large set of built-in rules (see the rules command) and supports selectively enabling or disabling groups of checks, adjusting severity or adding per-file exceptions via configuration files (pyproject.toml or other supported config locations).
Where automatic changes are safe, Ruff offers a –fix flow that applies corrections in place. For other changes that might alter runtime behavior it refuses to proceed unless explicitly asked to apply "unsafe" fixes. This separation prevents surprising behavior while still automating the low-risk housekeeping tasks that usually clutter reviews.
What it doesn't do
Ruff is not a silver bullet. First, it does not enable every rule that other toolchains provide by default. Some rule families are intentionally placed in preview and must be explicitly activated; the project authors keep these behind a preview flag until their behavior is stable and well-documented. That means a team migrating from flake8-plus-plugins should not assume parity out of the box: some checks will need configuration or explicit activation.
Second, Ruff does not automatically apply every suggested fix. If a suggested change could change program semantics, Ruff treats it as unsafe and will not apply it without your consent. Use the –unsafe-fixes flag only after reviewing the implications. This design prevents a linter from silently introducing behavior changes into a codebase.
Third, Ruff does not replace human judgment. It finds mechanical issues, unused code and many common pitfalls, but it does not replace design reviews, architectural discussion, or a careful security audit. Linting complements review; it does not substitute for it.
Fourth, Ruff does not yet replicate every third-party flake8 plugin. If a project depends on a plugin that produces critical, domain-specific diagnostics, you must either enable equivalent Ruff rules (when available) or continue using that plugin alongside Ruff. Migration requires checking which rules are covered and which remain missing or gated behind preview flags.
A practical example from our test illustrates these limits: selection of rule E302 (blank lines between functions) produced a mismatch between flake8 and Ruff when run without preview rules enabled. flake8 reported E302; Ruff returned "All checks passed" because the E3 family was in preview and not active. In other words, expect differences until you explicitly align rule selection.
Finally, if you need highly specialized statistics or reporting beyond Ruff's scope, you may still need additional tooling to compute the metrics you require.
How to use it
There are three common installation paths: pip inside a virtual environment, pipx for an isolated global install, or using one of the project-provided prebuilt executables for platforms that the releases target. Run the commands from your project folder unless you purposely point them at a different path.
Install with pip inside a virtual environment:
pip install ruff
Install globally in an isolated environment with pipx:
pipx install ruff
If you prefer a platform binary, download the appropriate release artifact from the GitHub releases page and place it on your PATH. Then you can run the executable directly without a Python runtime.
Basic checks run with the check subcommand against files or folders:
ruff check src/
Apply safe automatic fixes:
ruff check –fix src/
Apply fixes including those considered potentially unsafe (use with caution):
ruff check –fix –unsafe-fixes src/
Format files in place:
ruff format src/
List every rule Ruff knows about:
ruff rule –all
Print configuration guidance and the effective configuration:
ruff config
Show the installed Ruff version:
ruff –version
Notes on configuration: Ruff reads configuration from pyproject.toml (preferred) and other supported configuration files. You do not need to register Ruff anywhere to run it locally—install and run. For CI integration, add Ruff as a pipeline step that fails the build on diagnostic severity you choose; for pre-commit, configure a hook that runs Ruff on staged files. The language server and editor plugins enable live feedback for developers who want diagnostics while typing.
How Ruff fits in automated workflows with LLM-powered tools
-
Claude Code: when running commands inside a container or build tool controlled by an automation agent, invoke Ruff as you would from a shell, e.g. ruff check –fix src/. Ensure the runner image or container has Ruff installed or install it in an earlier pipeline step. Documentation: see the project docs (https://docs.astral.sh/ruff/).
-
Codex CLI: use Ruff in remote command executions and capture structured output for reporting. For example: ruff check –format=json src/ > ruff-report.json, then upload or process that JSON in your automation pipeline (link to JSON output docs at https://docs.astral.sh/ruff/).
-
Cursor (editor automation): configure your editor to run ruff check –fix ${file_path} on save or wire ruff format into a save action for instant formatting. Language-server integrations provide diagnostics and quick-fix commands that editors can expose.
Each environment needs Ruff available on PATH or installed in the environment the automation uses; otherwise install Ruff in the runner image or virtual environment and then call it as normal.
Drive it from the shell
Ruff is a traditional command-line tool with subcommands (check, format, rule, config, etc.). Typical commands for daily use are short and predictable:
ruff check –fix src/
and
ruff format src/
You do not need to run any daemon or register the tool to invoke it locally. If you add Ruff as a pre-commit hook or as a CI stage, the same commands are executed by the hook or pipeline runner. For large repositories, prefer scoping runs to changed packages or paths to avoid re-linting unrelated code on every change. The executables and subcommands are stable and intended for scripting in build systems and CI.
Our hands-on test
We exercised Ruff in a small, repeatable test case and recorded the results so readers can reproduce them. In a clean test folder we created a file containing deliberate problems: two unused imports and two assigned-but-unused variables. Running a single-file check produced four diagnostics: two F401 for the unused imports and two F841 for variables assigned but never used. Executing ruff check –fix on that file removed the two unused imports (the F401s) but left the two F841s untouched. Ruff classified those as unsafe to auto-fix and refused to modify them without –unsafe-fixes, which matches the documented behavior.
We measured runtime on a larger file of roughly 9,000 lines. Ruff completed the check in 0.168 seconds. For comparison, flake8 ran the same file in 5.406 seconds in the same measurement. That is a single measurement where Ruff was approximately 32 times faster; this is one measurement, not a broad benchmark. Another practical observation: selecting rule E302 failed in Ruff unless preview rules were enabled—flake8 reported E302 but Ruff returned "All checks passed" until the preview family was activated (the message was Selection E302 has no effect because preview is not enabled).
For completeness, these are the collected figures, each read from the source that means it. From GitHub (astral-sh/ruff): 51,183 stars, 2,651 forks, 2,297 open issues, MIT license, first commit 2022-08-09, last push 2026-11-11. From PyPI: latest version 0.17.4 published 2026-11-05, Requires-Python >=3.7, Windows wheel 10,292,922 bytes, source archive 5,357,750 bytes. PyPI download counts: 100,563,269 per week, 304,029,216 per month, 17,371,890 in a single day. The release executable measured 26,974,000 bytes. The rule count, 1,068, came from running ruff rule –all. The license is MIT according to the repository, while PyPI's own license field is empty — and we say so rather than filling it in.
Where useful, the figures above can be checked against the project's GitHub repository, its official documentation and the PyPI listing, all linked below.
What it costs
Here is what you actually pay to use Ruff, in tokens, space and money.
Tokens: zero. Ruff is not a server you register with a model — it loads no tool schema into any model's context. There is no context tax here, and that is not an estimate: it follows from how the tool works. You call it from the shell, the output stays in your terminal or in a file, and no model sees any of it unless you hand it over. That is the difference between a command-line tool and an MCP server, which carries the description of every tool it exposes into every call.
Space: one file, not an ecosystem. The executable is a single static artifact of 26,974,000 bytes (about 25.7 MB) — it does not need a Python runtime beside it, because it is written in Rust. Installed from PyPI, the Windows package is 10,292,922 bytes (about 9.8 MB) and the source archive is 5,357,750 bytes. It has no dependencies to pull in.
Money: zero. MIT licence, free, no account, no key, no subscription.
And time, which is the real return: in our test, on a 9,000-line file Ruff finished in 0.168 seconds while flake8 took 5.406 seconds on the same file. Every run of the check therefore saves roughly five seconds at that size — and in a CI pipeline that runs dozens of times a day, that is the number that counts.
When it pays off
Ruff is worth adopting when linting latency is a problem—teams with large codebases, frequent commits, or CI gates that slow down development gain the most. If your CI stages are dominated by linter runs or your local tooling discourages developers from running checks frequently, Ruff's speed and single-executable model reduce friction and make continuous checking practical.
It also pays when you prefer to consolidate tools: having linting, import sorting heuristics and formatting available from the same executable simplifies pipelines and lowers the cognitive load on developers who otherwise juggle multiple small tools. Because many rules are built in, teams often find they can remove several separate linters and rely on Ruff as the single source of truth.
Ruff is less attractive when your workflow depends on specific third-party flake8 plugins that Ruff does not replicate, or when critical rules live behind preview flags you cannot enable for policy reasons. Migration costs may outweigh gains for very small personal scripts where lint runtime is negligible; the real benefits emerge at team scale or in repositories that would otherwise repeat slow lint runs in CI.
A pragmatic migration approach is staged: start by running Ruff in parallel with your existing tools, compare reports over a period (a few weeks), enable safe fixes and formatting first, and progressively enable more aggressive checks once the team has adapted. Keep preview rules gated and communicate changes—preview rules can surface a large number of stylistic changes that require consensus.
The end
Ruff changes the economics of linting for Python. Its combination of speed, a broad rule set and built-in formatting makes it a practical choice for teams that want immediate feedback and low-cost CI. It has limits—preview rules, missing third-party plugin parity and guarded unsafe fixes—but those are manageable with a cautious rollout.
If you plan to replace an existing pipeline, run Ruff in parallel for a while, identify missing rules, and migrate incrementally. When configured carefully it reduces noisy nitpicks and frees reviewers to focus on design and correctness.
Sources:
https://github.com/astral-sh/ruff