Static Analysis — ruff

• Explain what a linter catches (and what it can't).
• Run ruff check and read its findings + rule codes.
• Auto-fix with ruff check --fix.
• Configure rules in pyproject.toml.

import os, sys           # sys is never used
def total(items):
    sum = 0               # shadows the built-in sum()
    for itm in items:
        total += itm      # BUG: should be 'sum', not 'total' (NameError at runtime)
    return sum

This file has three problems a linter spots instantly — without executing it: an unused import, a shadowed built-in, and an undefined-name bug that would crash. Static analysis catches them before your tests even run.

Install & run

pip install ruff

ruff check .              # lint the whole project
ruff check myfile.py      # lint one file

Reading the output

total.py:1:8: F401 [*] 'sys' imported but unused
total.py:5:9: F821 undefined name 'total'
total.py:3:5: A001 builtin 'sum' is shadowed

[*] = auto-fixable.  F401/F821 etc = rule codes (look them up).

• F4xx — Pyflakes: real errors (unused imports, undefined names).
• E/W — pycodestyle: style (spacing, line length).
• Hundreds more rule families, all in one fast tool.

Auto-fix the safe ones

ruff check --fix .        # fixes the [*] findings automatically
ruff check --fix --unsafe-fixes .   # also applies riskier fixes (review!)

Configure in pyproject.toml

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "B"]   # errors, pyflakes, import-sort, bugbear
ignore = ["E501"]               # e.g. don't enforce line length here

select chooses which rule families to enable. I even sorts your imports (replacing isort); B (flake8-bugbear) catches likely bugs like mutable default arguments.

Silence a line on purpose

import os  # noqa: F401   (intentionally unused — keep the linter quiet)

Use # noqa: <code> sparingly, and always name the specific rule so you don't accidentally hide other issues.

# messy.py — before
import os, json, sys
from collections import OrderedDict

def process(data = []):           # mutable default arg — classic bug (B006)
    result = OrderedDict()        # OrderedDict unneeded in modern Python
    for x in data :               # extra space before colon
        result[x]=x*2             # missing spaces around =
    unused = 42                   # assigned but never used (F841)
    return result

$ ruff check messy.py
messy.py:1:1: F401 'json' imported but unused
messy.py:1:1: F401 'sys' imported but unused
messy.py:4:18: B006 mutable default argument
messy.py:7:6: E203 whitespace before ':'
messy.py:9:5: F841 local variable 'unused' is never used
Found 5 errors.

# messy.py — after ruff check --fix + the B006 fix you do by hand
import os

def process(data=None):           # safe default
    data = data or []
    result = {}                   # plain dict
    for x in data:
        result[x] = x * 2
    return result

Read the diff

ruff flagged five issues — and auto-fixed the imports and spacing. The one it won't auto-fix (the mutable default data=[], a genuine bug source) it flags with B006 so you fix it deliberately. Run ruff on every file and these whole categories of bug simply stop happening. Next: pylint goes deeper.

ruff is a blazing-fast linter that statically catches unused/undefined names, likely bugs (bugbear), and style issues — without running your code. ruff check reports, --fix auto-fixes the safe ones, and pyproject.toml configures the rules. It's the cheapest quality win available. Next: pylint for deeper, more opinionated analysis.