How to configure recommended Ruff defaults

This guide shows how to configure Ruff with a curated set of linting rules that extend beyond the defaults. When starting a new project, it’s easier to enable a comprehensive set of rules from the beginning and selectively disable any that don’t fit the project’s needs, rather than gradually adding rules later when there’s already code to fix.

Adding the Configuration

Add the following to the project’s pyproject.toml file:

[tool.ruff.lint]
extend-select = [
    "F",        # Pyflakes rules
    "W",        # PyCodeStyle warnings
    "E",        # PyCodeStyle errors
    "I",        # Sort imports properly
    "UP",       # Warn if certain things can changed due to newer Python versions
    "C4",       # Catch incorrect use of comprehensions, dict, list, etc
    "FA",       # Enforce from __future__ import annotations
    "ISC",      # Good use of string concatenation
    "ICN",      # Use common import conventions
    "RET",      # Good return practices
    "SIM",      # Common simplification rules
    "TID",      # Some good import practices
    "TC",       # Enforce importing certain types in a TYPE_CHECKING block
    "PTH",      # Use pathlib instead of os.path
    "TD",       # Be diligent with TODO comments
    "NPY",      # Some numpy-specific things
]

Running the Linter

Check the project for issues:

uv run ruff check .

Automatically fix violations where possible:

uv run ruff check --fix .

Understanding the Rule Categories

Pyflakes (F)

Detects logical errors that would cause runtime failures, including undefined variables, unused imports, and invalid string formatting.

PyCodeStyle Errors (E) and Warnings (W)

Enforces PEP 8 conventions, catching indentation errors, incorrect comparisons (if x == None), and whitespace issues.

Import Sorting (I)

Ensures imports follow a consistent ordering convention, grouping standard library, third-party, and local imports predictably.

Python Upgrades (UP)

Modernizes code syntax to use newer Python features, suggesting f-strings over older formatting and updated type hint syntax.

Comprehensions (C4)

Identifies inefficient iteration patterns, flagging unnecessary list comprehensions wrapped in constructors and suggesting simpler alternatives.

Future Annotations (FA)

Encourages adding from __future__ import annotations, which simplifies forward references in type hints and reduces runtime overhead.

String Concatenation (ISC)

Detects implicit string concatenation of adjacent literals, making concatenation explicit and preventing bugs from missing commas.

Import Conventions (ICN)

Enforces standard import aliases (numpy as np, pandas as pd, matplotlib.pyplot as plt).

Return Practices (RET)

Improves function return patterns by flagging unnecessary return None statements and suggesting removal of superfluous else blocks.

Simplifications (SIM)

Suggests more elegant code patterns, including combined isinstance() checks, natural comparison order, and cleaner boolean logic.

Tidy Imports (TID)

Manages import quality by encouraging absolute imports and helping establish import conventions.

Type Checking Imports (TC)

Optimizes type-only imports by moving them into if TYPE_CHECKING: blocks, reducing import overhead while maintaining type-checking capability.

Pathlib Usage (PTH)

Recommends pathlib.Path over os.path functions for more object-oriented, cross-platform file handling.

TODO Discipline (TD)

Enforces conventions for TODO comments, requiring proper formatting and meaningful descriptions.

NumPy Conventions (NPY)

Flags deprecated NumPy type aliases and APIs, guiding migration to modern NumPy patterns.

Selective Rule Disabling

To disable specific rules that conflict with existing practices, add them to the ignore list:

[tool.ruff.lint]
extend-select = [
    # ... rules from above
]
ignore = [
    "TD003",  # Example: disable missing TODO link requirement
]