Ruff

ruff: Python Linter & Formatter

ruff (v0.15.12, Apr 2026) is three tools in one Rust binary: linter (ruff check), formatter (ruff format), and dependency analyzer (ruff analyze graph). It replaces Flake8, Black, isort, pyupgrade, and dozens more.

The built-in language server (ruff server) replaces the deprecated ruff-lsp package (archived Dec 2025).

Invocation

uv run ruff ...     # Project dependency (pinned version)
uvx ruff ...        # One-off (latest)
ruff ...            # Global install

Rule Selection: The Critical Decision

Default rules are minimal: only ["E4", "E7", "E9", "F"], catches syntax errors and undefined names but misses most quality rules. You almost certainly need to extend this.

select vs extend-select

Config inheritance trap: When a child config specifies select, the parent's ignore list is discarded. This surprises people with monorepo setups.

Specificity wins: More specific prefixes override less specific ones. select = ["E"] + ignore = ["E501"] enables all E rules except E501.

Recommended Selection Strategy

New project, start broad:

[tool.ruff.lint]
select = [
    "E", "W",    # pycodestyle
    "F",         # Pyflakes
    "I",         # isort
    "N",         # pep8-naming
    "UP",        # pyupgrade
    "B",         # flake8-bugbear
    "SIM",       # flake8-simplify
    "TC",        # flake8-type-checking
    "RUF",       # Ruff-specific
]
ignore = ["E501"]  # Let formatter handle line length

Library / open source, maximum strictness:

[tool.ruff.lint]
select = ["ALL"]
ignore = [
    # Formatter conflicts (MUST disable)
    "W191", "E111", "E114", "E117",
    "D206", "D300",
    "Q000", "Q001", "Q002", "Q003", "Q004",
    "COM812", "COM819",
    # Pydocstyle conflicts
    "D203", "D213",
    # Overly strict
    "D100", "D104",
    "ANN101", "ANN102",
    "FBT", "ERA001",
    "E501",
]

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["S101", "D", "ANN", "ARG"]
"scripts/**" = ["T20", "INP001"]
"**/__init__.py" = ["F401", "D104"]

Legacy migration, incremental:

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F"]
extend-select = [
    "I",      # Step 1: import sorting (safe, auto-fixable)
    "UP",     # Step 2: pyupgrade (mostly auto-fixable)
    # "B",    # Step 3: uncomment when ready
]

The ALL Selector

select = ["ALL"] enables every stable rule. Ruff auto-disables conflicting pairs (D203/D211, D212/D213), but being explicit is better practice. Preview rules require preview = true and are not included even with ALL.

Formatter Behavior

Configuration

[tool.ruff.format]
quote-style = "double"           # "double" | "single" | "preserve"
indent-style = "space"           # "space" | "tab"
skip-magic-trailing-comma = false
docstring-code-format = true     # Format code in docstrings
preview = false                  # Enable 2026 style guide

Rules That CONFLICT With the Formatter

When using ruff format, these lint rules should be avoided:

ignore = [
    "W191", "E111", "E114", "E117",  # Indentation
    "D206", "D300",                   # Docstring formatting
    "Q000", "Q001", "Q002", "Q003", "Q004",  # Quotes
    "COM812", "COM819",               # Commas
]

Also avoid ISC002 in Ruff's documented formatter-conflict case: ISC002 selected, ISC001 not selected, and flake8-implicit-str-concat.allow-multiline = false.

Known Deviations from Black

Ruff targets >99.9% parity with Black but has 23 intentional divergences. The most impactful:

E501 and the Formatter

The formatter makes best-effort line wrapping, it cannot always succeed. Comments, long strings, and URLs may exceed line-length. Either ignore E501 or set lint.pycodestyle.max-line-length higher than line-length.

Fix Safety Model

ruff check --fix .                    # Safe fixes only
ruff check --fix --unsafe-fixes .     # Include unsafe (review first!)
ruff check --fix --diff .             # Preview changes before applying

Override per-rule:

[tool.ruff.lint]
extend-safe-fixes = ["RUF015"]       # Promote to safe
extend-unsafe-fixes = ["F401"]        # Demote to unsafe (require --unsafe-fixes)

Suppression System

# Line-level
import os  # noqa: F401

# Block-level (new in 0.15.0)
# ruff: disable[E501]
LONG_VALUE = "..."
# ruff: enable[E501]

# File-level
# ruff: noqa: F401, E501

ruff check --select RUF100 --fix .    # Clean up unused noqa comments
ruff check --add-noqa .               # Auto-add noqa to all violations

Preview Mode

Preview is a staging area for new rules and formatter changes.

[tool.ruff.lint]
preview = true       # Expands defaults from 59 to 412 rules
explicit-preview-rules = true  # Require individual opt-in even with preview on

Preview rules are NOT activated by prefix selection or ALL, they require preview mode enabled. Use explicit-preview-rules = true to control which preview rules activate individually.

Dependency Graph Analysis

ruff analyze graph src/                          # File dependency graph (JSON)
ruff analyze graph --direction=dependents src/   # Reverse graph
ruff analyze graph --detect-string-imports src/  # Include dynamic imports

Use cases: selective test running, dead code detection, circular import detection.

Configuration

File precedence: .ruff.toml > ruff.toml > pyproject.toml (nearest wins, no merging across levels).

Falls back to ~/.config/ruff/ruff.toml when no project config exists.

[tool.ruff]
target-version = "py312"         # Inferred from requires-python if unset
line-length = 88
src = ["src", "tests"]           # First-party import classification
required-version = "==0.15.12"   # Pin version with a PEP 440 specifier
extend = "../pyproject.toml"     # Inherit parent config

[tool.ruff.lint.isort]
known-first-party = ["myproject"]
combine-as-imports = true

[tool.ruff.lint.pydocstyle]
convention = "google"            # "google" | "numpy" | "pep257"

[tool.ruff.lint.flake8-type-checking]
runtime-evaluated-base-classes = ["pydantic.BaseModel"]
runtime-evaluated-decorators = ["attrs.define"]

For the complete rule catalog snapshot, see references/rules.md. For full configuration reference, see references/configuration.md.

Debugging

ruff check --show-settings .     # Dump resolved config
ruff check --show-files .        # List files that would be checked
ruff check --statistics .        # Count violations per rule
ruff rule E501                   # Explain a specific rule
ruff linter                      # List all available linters

Non-Obvious Gotchas

Anti-Patterns

What This Skill is NOT

• Not a replacement for ruff --help or ruff rule <CODE> for specific rule docs
• Not for type checking (use ty)
• Not for package management (use uv)
• Not for third-party Flake8 plugins that ruff hasn't re-implemented

Ruff Configuration Reference

File Precedence

.ruff.toml > ruff.toml > pyproject.toml (nearest wins, no merging across directory levels)

User-level fallback: ~/.config/ruff/ruff.toml (Linux/macOS) or ~\AppData\Roaming\ruff\ruff.toml (Windows)

pyproject.toml vs ruff.toml

# pyproject.toml              # ruff.toml (no [tool.ruff] prefix)
[tool.ruff]                   line-length = 100
line-length = 100
                              [lint]
[tool.ruff.lint]              select = ["E", "F"]
select = ["E", "F"]
                              [format]
[tool.ruff.format]            quote-style = "single"
quote-style = "single"
                              [lint.isort]
[tool.ruff.lint.isort]        known-first-party = ["mymod"]
known-first-party = ["mymod"]

Config Inheritance

[tool.ruff]
extend = "../pyproject.toml"  # Inherit parent config, override locally

Top-Level Settings

[tool.ruff]
target-version = "py312"      # py37-py315, inferred from requires-python if unset
line-length = 88
indent-width = 4
src = ["src", "tests"]        # First-party import classification
required-version = "==0.15.12" # Pin version with a PEP 440 specifier
respect-gitignore = true
include = ["*.py", "*.pyi"]
exclude = [".venv", "migrations"]
extend-include = ["*.ipynb"]
extend-exclude = ["generated"]
per-file-target-version = { "legacy/**" = "py38" }

Lint Settings

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F"]  # Baseline (replaces defaults)
extend-select = ["B", "I"]         # Additive
ignore = ["E501"]                   # Subtractive
fixable = ["ALL"]                   # Which rules can be auto-fixed
unfixable = ["F401"]                # Block auto-fix for these
extend-safe-fixes = ["RUF015"]     # Promote to safe
extend-unsafe-fixes = ["F401"]     # Demote to unsafe
preview = false
explicit-preview-rules = false     # Require individual preview opt-in
task-tags = ["TODO", "FIXME", "XXX", "HACK"]
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
external = ["V"]                   # Preserve in noqa for external tools
logger-objects = ["myapp.logging.logger"]
typing-modules = ["myapp.types"]

Per-File Ignores

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401", "E402"]
"**/{tests,docs}/*" = ["S101", "D"]
"**/conftest.py" = ["ARG"]
"scripts/**" = ["T20", "INP001"]
"*.ipynb" = ["T20", "E402"]
"migrations/**" = ["E501"]

Lint Sub-Settings

isort

[tool.ruff.lint.isort]
known-first-party = ["myproject"]
known-third-party = ["wandb"]
combine-as-imports = true
force-single-line = false           # WARNING: conflicts with formatter
lines-after-imports = 2
required-imports = ["from __future__ import annotations"]

pydocstyle

[tool.ruff.lint.pydocstyle]
convention = "google"               # "google" | "numpy" | "pep257"

pylint

[tool.ruff.lint.pylint]
max-args = 5
max-returns = 6
max-branches = 12
max-statements = 50
max-locals = 15
max-nested-blocks = 5
max-bool-expr = 5
max-public-methods = 20
allow-magic-value-types = ["int", "str"]

mccabe

[tool.ruff.lint.mccabe]
max-complexity = 10

flake8-type-checking

[tool.ruff.lint.flake8-type-checking]
runtime-evaluated-base-classes = ["pydantic.BaseModel"]
runtime-evaluated-decorators = ["attrs.define"]
quote-annotations = false
strict = false

flake8-tidy-imports

[tool.ruff.lint.flake8-tidy-imports]
ban-relative-imports = "parents"
banned-api = { "os.path.join" = { msg = "Use pathlib.Path instead" } }

flake8-import-conventions

[tool.ruff.lint.flake8-import-conventions.aliases]
numpy = "np"
pandas = "pd"
matplotlib.pyplot = "plt"
seaborn = "sns"
polars = "pl"

flake8-pytest-style

[tool.ruff.lint.flake8-pytest-style]
fixture-parentheses = false
mark-parentheses = false

flake8-builtins

[tool.ruff.lint.flake8-builtins]
ignorelist = ["id", "type"]

pycodestyle

[tool.ruff.lint.pycodestyle]
max-doc-length = 88
max-line-length = 120  # Set higher than line-length for E501 tolerance
ignore-overlong-task-comments = false

pyflakes

[tool.ruff.lint.pyflakes]
allowed-unused-imports = ["myapp.compat"]

Format Settings

[tool.ruff.format]
quote-style = "double"              # "double" | "single" | "preserve"
indent-style = "space"              # "space" | "tab"
line-ending = "auto"                # "auto" | "lf" | "cr-lf" | "native"
skip-magic-trailing-comma = false
docstring-code-format = false
docstring-code-line-length = "dynamic"
preview = false
exclude = []

Analyze Settings

[tool.ruff.analyze]
detect-string-imports = false
direction = "dependencies"          # "dependencies" | "dependents"
type-checking-imports = true
include-dependencies = {}

Suppression Comments

import os  # noqa: F401             # Line-level
# ruff: disable[E501]               # Block-level (0.15.0+)
# ruff: enable[E501]
# ruff: noqa: F401, E501            # File-level
# isort: skip_file                   # isort file skip
# isort: off / # isort: on           # isort block
# fmt: off / # fmt: on               # Format block
a = [1,2,3]  # fmt: skip            # Format skip (statement-level)

Format Suppression in Markdown (Preview)

<!-- fmt:off -->
<!-- fmt:on -->
<!-- blacken-docs:off -->
<!-- blacken-docs:on -->

isort Action Comments

# isort: skip_file
# isort: off / # isort: on
# isort: skip          # Skip next import
# isort: split         # Force section break
# ruff: isort: skip_file  # Ruff-prefixed variant

Ruff Rule Family Map (Apr 2026)

Use ruff linter and <https://docs.astral.sh/ruff/rules/> for authoritative current counts. This file is a routing map for deciding which rule families matter, not a version-pinned census.

Framework-Specific

Core Python

Pylint Re-implementations

Flake8 Plugin Re-implementations

Note: TCH is a legacy alias for TC. Both work, prefer TC in new configs.

Other Tool Re-implementations

Ruff-Specific

Rules Stabilized in Recent Releases

0.15.0 (Feb 2026)

ASYNC212/240/250 (blocking calls in async), B912 (map without strict), UP042 (replace StrEnum), FURB110/171, RUF060/061/064, RUF102-104

0.13.0 (Sep 2025)

AIR002/301/302/311/312 (Airflow 3 migration), UP050, FURB116, RUF043/059

0.12.0 (Jul 2025)

UP045/046/047/049 (PEP 604/695 syntax), PLR1733, PLW0177/1641, FURB122/132/157/162/166, RUF028/049/053/057/058

Conflicting Rule Pairs