Ruff Setup skill for Codex

Done well means one Ruff version pinned across local, pre-commit and CI; a rule selection chosen on purpose (not ALL, not just the defaults); no rules that fight the formatter; and ruff check plus ruff format --check both clean in CI, with any legacy violations either fixed or recorded as explicit noqa comments.

Inspect

ls pyproject.toml ruff.toml .ruff.toml setup.cfg .flake8 tox.ini .isort.cfg .pre-commit-config.yaml 2>/dev/null
grep -nA30 '^\[tool\.\(ruff\|black\|isort\|flake8\)' pyproject.toml
grep -nE 'ruff|flake8|black|isort|pyupgrade|autoflake|pylint' requirements*.txt pyproject.toml .pre-commit-config.yaml 2>/dev/null

Read AGENTS.md for the dependency manager (uv, poetry, pip-tools) and check commands. Note project.requires-python; Ruff infers target-version from it.

Install

uv add --dev ruff==0.17.3        # or: poetry add --group dev [email protected] ; pip install ruff==0.17.3

Use the current release at install time and pin it exactly: new Ruff versions add rules and promote preview behaviour, which can turn CI red on unrelated PRs. Installing needs network; in an offline Codex sandbox ask for approval or use a Ruff already in the venv.

Reference configuration

# pyproject.toml
[tool.ruff]
line-length = 100
extend-exclude = ["migrations/versions", "src/generated"]
# target-version comes from project.requires-python; set it only if that is missing

[tool.ruff.lint]
select = [
  "E4", "E7", "E9", "F",   # Ruff defaults: real errors only
  "I",                     # isort
  "B",                     # bugbear: likely bugs
  "UP",                    # pyupgrade for the target version
  "SIM",                   # simplifications
  "C4",                    # comprehensions
  "PT",                    # pytest style
  "RUF",                   # Ruff-specific, includes unused-noqa
]
ignore = ["SIM108"]        # ternary rewrite: taste, often less readable

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

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

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

Choosing rules

Tier	Prefixes	Use when
Baseline	E4 E7 E9 F (default)	Never less than this
Recommended for most code	+ I B UP SIM C4 RUF	Default choice for applications and libraries
Domain add-ons	PT (pytest), DJ (Django), FAST (FastAPI), ASYNC (asyncio), S (bandit security), DTZ (timezones), PD/NPY (data)	The project uses that domain
Library polish	D with a convention, N, PL*, RET, PTH, TC	Public libraries with a mature codebase
Avoid	ALL	Every upgrade silently enables new rules; also selects conflicting pairs
Leave off with ruff format	W191 E111 E114 E117 D206 D300 Q000-Q003 COM812 COM819, and ISC001/ISC002 if Ruff warns	They conflict with the formatter; Ruff prints a warning when they are on

Explain each non-default prefix in a comment, as above. For any single code: ruff rule B008 prints its rationale and fix behaviour offline.

Migrating from flake8, Black and isort

For the plugin-to-prefix table and settings translation (max-complexity, isort profile, Black string normalisation), read references/flake8-plugin-map.md when the project has an existing flake8, isort, Black or pylint configuration.

- [ ] 1. Record baseline: current tool versions, violation counts per code
- [ ] 2. Translate settings and plugins to [tool.ruff] (reference file)
- [ ] 3. ruff check --statistics: compare counts with the old flake8 run
- [ ] 4. Formatter: ruff format --diff; review differences from Black
- [ ] 5. Commit config; commit safe autofixes; commit the reformat separately
- [ ] 6. Backfill noqa for what remains (or fix it) and enable RUF100
- [ ] 7. Replace old tools in pre-commit, CI, dev deps and editor settings
- [ ] 8. Add mass-change SHAs to .git-blame-ignore-revs

Commands for each step:

flake8 --statistics -qq . | sort -rn | head -30         # before (old tool still installed)
ruff check --statistics .                               # after: compare codes and counts
ruff check --fix .                                      # safe fixes only
ruff check --fix --unsafe-fixes --diff .                # preview unsafe fixes; apply only after review
ruff format --diff . | head -100                        # Black -> Ruff formatter differences
ruff check --add-noqa .                                 # baseline remaining violations as noqa comments
ruff check --extend-select RUF100 --fix .               # later: remove noqa that no longer apply

• Ruff’s formatter is designed as a drop-in for Black and differs on a small number of edge cases. Expect a handful of changed files, not hundreds; hundreds means a setting (line length, quote style, magic trailing comma) was not carried over.
• ruff format does not sort imports. Keep I selected and run ruff check --fix before ruff format.
• --add-noqa is a debt ledger, not a fix. Prefer fixing when counts are small; use noqa backfill when a large codebase adopts new rules, and tell the user how many lines it touched.

Running everywhere the same way

ruff check . && ruff format --check .                  # CI gate
ruff check --output-format=github .                    # GitHub Actions annotations
ruff check --show-settings src/myapp/api.py | head -50 # resolved settings for one file
ruff check --show-files . | head                       # which files Ruff will lint

pre-commit (lint with --fix before format):

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.17.3              # same version as the dev dependency
  hooks:
    - id: ruff-check
      args: [--fix]
    - id: ruff-format

Editor: the Ruff VS Code extension uses the project’s ruff from the environment when it can; set it as the Python formatter and disable Black, isort and flake8 extensions so they do not compete.

Configuration discovery gotchas

• Ruff uses the closest pyproject.toml (with a [tool.ruff] section), ruff.toml or .ruff.toml to each file. A nested config replaces the parent entirely unless it says extend = "../pyproject.toml". In monorepos, give packages extend or keep one root config.
• exclude replaces Ruff’s default exclusions (.venv, build, node_modules, and so on); use extend-exclude instead.
• Files passed explicitly on the command line are linted even if excluded, unless force-exclude = true. Set it when pre-commit or editors pass paths directly.
• per-file-ignores keys are globs relative to the config file’s directory.
• select in a nested config overrides, extend-select adds. Mixing them up silently drops rules.

Verify

1. ruff check --statistics . shows only the codes you expect, with counts you can explain against the baseline.
2. ruff check . && ruff format --check . exit 0 locally and in CI.
3. pre-commit run --all-files produces no changes on a clean tree.
4. The Ruff version is identical in the lockfile, pre-commit rev and CI.

Report: Ruff version, selected prefixes with one-line reasons, before/after violation counts, files reformatted, number of noqa comments added, old tools removed.