What Is Ruff? The Python Linter and Formatter Explained
Ruff is a fast Python linter and formatter written in Rust. What it replaces, how to install and configure it, and the commands you will actually use.
Ruff is a Python linter and code formatter written in Rust, and it replaces several separate tools with one fast one. It checks your code for errors and style problems (ruff check) and formats it (ruff format), replacing the usual mix of Flake8, isort, pyupgrade and Black.
What Ruff does
- Linting: finds unused imports, undefined names, likely bugs and style problems across hundreds of rules.
- Fixing: many rules have automatic fixes, applied with
ruff check --fix. - Formatting:
ruff formatrewrites code to a consistent style, compatible with Black. - Import sorting: the
Irule set does what isort does. - Editor support:
ruff serveris a language server, so diagnostics and formatting work in any editor that supports the language server protocol.
Install and run it
uv add --dev ruff # in a uv project
# or
pip install ruff
ruff check . # lint
ruff check --fix . # lint and apply safe fixes
ruff format . # format
ruff format --check . # report files that would change (good for CI)Configure it
Ruff reads configuration from pyproject.toml (or ruff.toml):
[tool.ruff]
line-length = 88
target-version = "py312"
[tool.ruff.lint]
extend-select = ["ANN"] # add rules on top of the defaults
ignore = ["E501"] # turn one offRuff enables a default set of rules without any configuration. The documentation describes it as the correctness, suspicious, complexity, performance and style categories, and in Ruff 0.17.3 that comes to about 400 rules. Run ruff check --show-settings to see exactly what your version enables. Use extend-select to add rule groups, such as ANN for type annotations, on top of the defaults. Using select instead replaces the defaults entirely, which usually enables fewer rules, not more. Add groups gradually rather than enabling everything at once.
Ruff vs the tools it replaces
| Tool | Job | Ruff equivalent |
|---|---|---|
| Flake8 | Linting | ruff check |
| isort | Import sorting | I rules |
| pyupgrade | Modernise syntax | UP rules |
| Black | Formatting | ruff format |
| Pylint | Deeper linting | Partly, via PL rules |
For the full comparisons, see Black vs Ruff vs autopep8 and Ruff vs Pylint vs Flake8. If you are wondering what Black itself does, see what Black does.
What Ruff does not do
Ruff doesn’t type-check. Pair it with a type checker; see Python type checkers compared. It also doesn’t run your tests: that’s pytest.
Using Ruff in CI and your editor
In CI, run ruff check . and ruff format --check . so the build fails on lint errors or unformatted code. In your editor, install the Ruff extension or language server so problems appear as you type. Ruff is listed in our resources.
Frequently Asked Questions
What is Ruff in Python?
Ruff is a Python linter and code formatter from Astral, written in Rust. It checks code for errors and style problems with ruff check and formats it with ruff format, in one tool.
What does Ruff replace?
Ruff can replace Flake8 and many of its plugins, isort for import sorting, and pyupgrade, and its formatter is a drop-in alternative to Black. You configure all of it in one place.
Is Ruff a replacement for Black?
Ruff’s formatter is designed to be a drop-in replacement for Black with highly compatible output. You can switch with ruff format and keep nearly identical formatting.
Is Ruff a type checker?
No. Ruff does linting and formatting. For type checking, use mypy, Pyright or ty, which is also from Astral.
How do I install and run Ruff?
Install it with uv add —dev ruff, pip install ruff or uv tool install ruff. Then run ruff check . to lint, ruff check —fix . to apply safe fixes, and ruff format . to format.