Use Ruff as the Single Linter and Formatter, Enforce Types with mypy

The modern Python code quality stack has consolidated around two tools: Ruff for linting and formatting, mypy (or pyright) for type checking. Ruff replaces Black, isort, flake8, pyupgrade, autoflake, and all flake8 plugins with a single Rust-powered binary that is 10-100x faster. Every major package -- FastAPI, Pydantic, httpx, Polars, Rich, pytest, attrs -- has migrated to Ruff. There is no credible alternative for new projects.

Without this consolidation, teams juggle conflicting configurations across six or more tools, deal with parser incompatibilities, and waste CI minutes. Without type checking in CI, a

py.typed

Ruff Rule Sets

Start with an explicit

select

select = ["ALL"]

Recommended starting set

[tool.ruff.lint]
select = [
    "F",      # Pyflakes -- undefined names, unused imports
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "I",      # isort -- import sorting
    "N",      # pep8-naming -- naming conventions
    "UP",     # pyupgrade -- modernize syntax
    "B",      # flake8-bugbear -- common bugs
    "SIM",    # flake8-simplify -- simplifiable code
    "C4",     # flake8-comprehensions -- better comprehensions
    "RUF",    # Ruff-specific rules
    "PERF",   # Perflint -- performance anti-patterns
]
ignore = ["E501"]  # Line too long -- handled by formatter

Rule tier reference

F

E

W

I

UP

B

N

SIM

C4

RUF

PERF

S

D

TCH

PT

C90

PLR

TCH

A

FBT

ARG

ERA

ANN

Per-file ignores

Relax rules where they create noise rather than value:

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101", "D", "ANN", "PLR2004"]
"__init__.py" = ["F401"]   # Allow unused imports (re-exports)

Ruff Configuration

[tool.ruff]
target-version = "py310"    # Match your requires-python lower bound
line-length = 88            # Black default, de facto standard
src = ["src"]               # Critical for correct first-party import detection

[tool.ruff.lint.isort]
known-first-party = ["my_package"]

[tool.ruff.format]
docstring-code-format = true

Set

src = ["src"]

Formatting with Ruff Format

Use

ruff format

quote-style = "double"

line-length = 88

skip-magic-trailing-comma = false

docstring-code-format = true

Type Checking: mypy vs pyright

strict = true

typeCheckingMode = "strict"

For library authors: Run both. Different checkers catch different issues. Pydantic, FastAPI, and httpx do this.

mypy strict configuration

[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_configs = true
enable_error_code = ["ignore-without-code", "redundant-cast", "truthy-bool"]

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

Always specify error codes in

# type: ignore[error-code]

# type: ignore

PGH003

Modern Type Hints

Use the newest syntax your minimum Python version supports. Ruff's

UP

List[str]

Dict[str, Any]

list[str]

dict[str, Any]

Optional[str]

Union[str, int]

str | None

str | int

TypeVar("T")

Generic[T]

class Foo[T]:

TypeAlias = Union[...]

type Alias = str | int

from __future__ import annotations

Ship py.typed

Every typed package must include an empty

py.typed

src/my_package/
    __init__.py
    py.typed        # Empty file -- its presence signals typed package
    core.py

Add the PyPI classifier:

"Typing :: Typed"

TYPE_CHECKING guard

Move type-only imports behind

TYPE_CHECKING

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from heavy_module import ExpensiveClass

Ruff's

TCH

Pre-commit Hooks

Collapse the entire pre-commit config to two Ruff hooks plus basic file hygiene. Do not add mypy, pytest, or security scanners -- they are too slow for pre-commit and belong in CI.

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-toml
      - id: check-added-large-files
        args: ["--maxkb=500"]
      - id: check-merge-conflict
      - id: debug-statements

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

Run

ruff

--fix

ruff-format

Reference Configuration

Complete

pyproject.toml

# -- Ruff ---------------------------------------------------------
[tool.ruff]
target-version = "py310"
line-length = 88
src = ["src"]

[tool.ruff.lint]
select = ["F", "E", "W", "I", "N", "UP", "B", "SIM", "C4", "RUF", "PERF", "TCH", "C90"]
ignore = ["E501"]

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101", "PLR2004"]
"__init__.py" = ["F401"]

[tool.ruff.lint.isort]
known-first-party = ["my_package"]

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

[tool.ruff.format]
docstring-code-format = true

# -- mypy ----------------------------------------------------------
[tool.mypy]
python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_configs = true
enable_error_code = ["ignore-without-code", "redundant-cast", "truthy-bool"]

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

# -- Dependency group ----------------------------------------------
[dependency-groups]
lint = ["ruff>=0.9", "mypy>=1.14"]

Review Checklist

When reviewing code for quality tooling and type safety:

• Ruff is the sole linter and formatter -- no Black, isort, flake8, or their plugins installed separately

• tool.ruff.lint.select

  uses explicit opt-in, not

  select = ["ALL"]

  with a long ignore list

• src = ["src"]

  is set in

  [tool.ruff]

  for src-layout projects

• E501

  is in the ignore list when using

  ruff format

  (formatter handles line length)
• mypy runs in strict mode (

  strict = true

  ) with

  enable_error_code = ["ignore-without-code"]

• No bare

  # type: ignore

  comments -- all have specific error codes

• py.typed

  marker file exists in the package root and is included in the wheel
• Type hints use modern syntax appropriate for the minimum Python version (

  list[str]

  ,

  str | None

  )
• Pre-commit config contains only Ruff hooks and file hygiene -- no mypy, pytest, or security scanners

• ruff

  hook runs before

  ruff-format

  in pre-commit ordering
• Type checkers run in CI, not in pre-commit

• per-file-ignores

  relaxes rules for tests and

  __init__.py

  re-exports
• McCabe complexity threshold is set (

  max-complexity = 10

  ) if

  C90

  is enabled