Ruff: The Lightning‑Fast All‑In‑One Python Linter and Formatter

What is Ruff?

Ruff is a Rust‑written Python code checker and formatter designed to replace Flake8, Black, isort, pyupgrade, and autoflake. Its goal is to be 10 to 100 times faster than the existing tools while providing a unified interface for code quality management.

Speed Benchmark

Official data shows that linting a large pandas codebase with Flake8 takes about 30 seconds, whereas Ruff completes the same check in 0.5 seconds, enabling real‑time feedback on file save.

Installation

Install Ruff with a single command:

# Recommended using uv for a fast experience
uv add ruff --dev
# Or using pip
pip install ruff

Basic Usage Example

Given a “dirty” file example.py containing unused imports and variables:

# example.py – a file with issues
from typing import Iterable
import os  # unused import
import sys  # unused import

def sum_even_numbers(numbers: Iterable[int]) -> int:
    """Return the sum of all even numbers."""
    return sum(num for num in numbers if num % 2 == 0)

unused_var = 42  # defined but never used

Running the lint command: ruff check example.py produces:

example.py:3:8: F401 `os` imported but unused
example.py:4:8: F401 `sys` imported but unused
example.py:11:1: F841 Local variable `unused_var` is assigned to but never used
Found 3 errors.
[*] 2 fixable with the `--fix` option.

Two of the issues can be automatically fixed: ruff check --fix example.py After fixing, the unused import statements are removed, and the file becomes cleaner.

Formatting the file is equally simple: ruff format example.py The command reports 1 file reformatted and applies consistent style (e.g., indentation and line breaks).

Configuration

Ruff reads configuration from pyproject.toml, ruff.toml, or .ruff.toml. A typical configuration looks like:

[tool.ruff]
line-length = 88          # match Black's default
target-version = "py310"

[tool.ruff.lint]
select = [
    "E",  # pycodestyle errors
    "W",  # pycodestyle warnings
    "F",  # Pyflakes checks
    "UP", # pyupgrade
    "B",  # flake8-bugbear
    "I",  # isort replacement
    "C4", # flake8-comprehensions
]
ignore = ["E501"]  # ignore line length, let formatter handle it

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false

Ruff also supports per‑file rule overrides, for example:

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"]   # allow asserts in tests
"**/__init__.py" = ["F401"]   # ignore unused imports in package init files

Migrating from Existing Tools

If a project already uses Black, isort, and Flake8, Ruff can ingest the old configuration and replace those tools without pain.

Editor Integration (VS Code Example)

Add the official Ruff extension and configure settings.json:

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.organizeImports": "always",
      "source.fixAll": "always"
    }
  }
}

This makes saving a file automatically format it and fix all fixable issues.

Pre‑commit Hook

Configure .pre-commit-config.yaml to run Ruff before each commit:

repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.12.8
  hooks:
  - id: ruff
    args: [--fix]
  - id: ruff-format

This ensures that code violating the style cannot be committed.

CI/CD Integration (GitHub Actions Example)

name: Lint & Format
on: [push, pull_request]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Run Ruff
      uses: astral-sh/ruff-action@v1
      with:
        args: "check --fix ."
    - name: Check Formatting
      run: ruff format --check .

This pipeline guarantees that every pull request passes Ruff’s lint and format checks.

Conclusion

Ruff delivers extreme speed, an all‑in‑one lint‑and‑format solution, straightforward configuration, and seamless integration with modern development workflows (editors, Git, CI). It effectively addresses the long‑standing pain points of slow, fragmented Python code‑quality tooling.