Python Lint

python-lint

Purpose

Configure Ruff as the single linter and formatter for a Python package — replacing Black, Flake8 (+ plugins), isort, and pyupgrade — with an explicit rule set in pyproject.toml, then drive ruff check and ruff format --check to a clean exit. Covers fresh setup, migration from the legacy stack, rule tuning, and fixing lint or format failures. Every command below runs in the user's package repository.

When NOT to use

• Type errors / mypy / pyright / ty — Ruff performs no type inference; ANN

rules only police annotation style. The python-typing skill, if installed, owns this.

• Pre-commit wiring (.pre-commit-config.yaml, hook rev pinning, staged-file

runs) — the python-precommit skill. This skill only defines what Ruff should do.

• CI workflow YAML (GitHub Actions jobs, matrices, caching) — the python-ci

skill. This skill supplies the commands a CI job should run, not the workflow.

• Formatting YAML / JSON / TOML / Markdown prose — Ruff formats Python only,

by deliberate maintainer decision (astral-sh/ruff#10738); the python-precommit skill covers non-Python files.

• Running Ruff automatically on agent edits (Claude Code hooks) — the

agent-guardrails skill.

Workflow

1. Inspect before touching anything

ls .flake8 .isort.cfg setup.cfg tox.ini ruff.toml .ruff.toml 2>/dev/null
grep -nE '^\[tool\.(ruff|black|isort)|^\[flake8\]|^\[isort\]' pyproject.toml setup.cfg tox.ini 2>/dev/null
grep -n 'requires-python' pyproject.toml

Pick the path: fresh setup (steps 2–3), migration off Black/Flake8/isort (step 5), tuning an existing config (step 4), or fixing a red lint gate (step 6).

2. Install a pinned Ruff

uv add --dev "ruff==0.15.6"        # example pin — check the latest release and pin that
# one-off, no project change:
uvx --from 'ruff==0.15.6' ruff check .

No-uv fallback (once, applies to every command below): python -m pip install 'ruff==0.15.6' and drop the uv run prefix.

Why pin — formatter output and the rule catalog change between minor releases (the 0.15 release shipped a "2026 style guide" that changed lambda and empty-line formatting; see astral.sh/blog/ruff-v0.15.0). An unpinned Ruff makes local, teammate, and CI runs disagree — the top reported lint-workflow failure. Optionally enforce the pin in config with required-version = "0.15.6" under [tool.ruff]. Note that uv format (uv 0.10.0+) runs Ruff's formatter under the hood — the same pinning logic applies.

3. Write the config (fresh setup)

All Ruff config lives in pyproject.toml. Keep exactly one config file — a ruff.toml next to a [tool.ruff] section is a recipe for confusion. Starter:

[tool.ruff]
target-version = "py311"          # lowest Python you support; gates UP rewrites
line-length = 88
extend-exclude = ["migrations"]   # generated code, if any

[tool.ruff.lint]
select = [
    "E", "W",   # pycodestyle
    "F",        # pyflakes
    "I",        # isort (import sorting)
    "UP",       # pyupgrade
    "B",        # flake8-bugbear
    "C4",       # flake8-comprehensions
    "SIM",      # flake8-simplify
    "RUF",      # Ruff-specific rules
]
ignore = ["E501"]                 # line length is the formatter's job

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"]        # assert is fine in tests (relevant once S is on)
"__init__.py" = ["F401"]          # re-exports

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

[tool.ruff.format]
quote-style = "double"
docstring-code-format = true      # formats Python snippets inside docstrings

Non-obvious decisions baked into this block:

• Ruff's out-of-the-box rule set is only E + F. A team that "installed

Ruff" without select gets far less coverage than its old Flake8+plugins stack. Always write an explicit select.

• ignore = ["E501"] whenever the formatter is enabled — ruff format already

wraps at line-length; linting it too double-reports on lines the formatter cannot break (URLs, long strings).

• target-version gates UP (pyupgrade) rewrites. If unset, Ruff falls back

to project.requires-python; if that is also absent it assumes py310, and autofixes can emit syntax that crashes older supported runtimes.

• Avoid select = ["ALL"] — it silently enables every new rule on every Ruff

upgrade, breaking checks unpredictably. Official guidance is to start narrow and grow one category at a time (docs.astral.sh/ruff/linter/).

Deeper rule catalog, tier strategy, and sub-table options (isort, pydocstyle, bugbear): references/rule-selection.md.

4. Tune an existing config

• Noise in one area (tests, scripts, notebooks) → scope it with

[tool.ruff.lint.per-file-ignores]; never delete the rule from select globally because tests complain. Common: "tests/**/*.py" = ["S101", "PLR2004"], "scripts/*" = ["T201"].

• A single intentional violation → # noqa: with the specific code and a

short reason. Bare # noqa hides every rule on the line.

• Codes from non-Ruff tools in # noqa comments (custom Flake8 plugin) →

declare external = ["XX"] in [tool.ruff.lint], or RUF100 strips those comments on the next --fix.

• Widen coverage one prefix at a time ("S", "PT", "PTH", …), run

uv run ruff check . after each addition, and fix or scope before adding more.

• Sanity-check the result: python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root .

(read-only; flags E501 double-reporting, ALL, formatter-conflicting rules, leftover legacy configs, missing target-version).

5. Migrate from Black / Flake8 / isort

Full mapping tables (commands, config keys, Flake8-plugin→prefix) and the large-legacy-codebase strategy: references/migration.md. The sequence:

1. Translate config first. [tool.black] → [tool.ruff] + [tool.ruff.format],

[tool.isort]/.isort.cfg → [tool.ruff.lint.isort] (kebab-case keys), .flake8 → select/ignore/per-file-ignores. Ruff never reads [tool.black] or .flake8 — anything not translated is silently lost.

1. Check plugin parity. For each Flake8 plugin in use, confirm a Ruff prefix

exists (table in the reference). A business-critical plugin with no equivalent → hybrid: keep Flake8 scoped to that plugin, add its codes to external = [...].

1. One-time cleanup as its own reviewed commit, before any gate is switched:

``bash uv run ruff check . --fix && uv run ruff format . ` Review the diff — Ruff's formatter is close to Black on large codebases but not byte-identical; deviations are documented at [docs.astral.sh/ruff/formatter/black/](https://docs.astral.sh/ruff/formatter/black/). For a large reformat, record the commit in .git-blame-ignore-revs`.

1. Retire the old stack in the same PR: remove black/flake8/isort (and their

plugins) from dev dependencies; delete .flake8, .isort.cfg, [tool.black], [tool.isort]. Two active formatters will fight over the same lines (astral-sh/ruff#1307).

1. Tell the user to repoint whatever invoked the old tools — pre-commit hooks

(python-precommit skill) and CI jobs (python-ci skill). Provide only the commands: ruff check . and ruff format --check ..

An existing Black+Flake8 setup that works and hurts nobody is a valid reason to not migrate — churn has cost. Migrate when there is friction (speed, config sprawl, plugin abandonment), not for fashion.

6. Fix lint / format failures

uv run ruff check . --fix    # 1. autofix what's safe
uv run ruff format .         # 2. THEN format — fixes can leave code needing reformat
uv run ruff check .          # 3. see what's left; --fix exiting clean != zero violations

Order matters: --fix rewrites imports/comprehensions that then need reformatting. For what remains:

• Fix the code. Reach for suppressions only when the violation is intentional, and

then the narrowest one: specific # noqa: > per-file-ignores > global ignore. Never make a red gate green by deleting rules from select.

• Some fixes are deliberately held back as unsafe (could change behavior). Review

them explicitly with uv run ruff check . --fix --unsafe-fixes --diff before applying.

• In GitHub Actions logs, uv run ruff check . --output-format=github emits

file/line annotations on the PR (the workflow YAML itself is python-ci territory).

7. Verify done

uv run ruff check . && uv run ruff format --check . && echo LINT-OK
python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root .

Output spec

Done means all of:

• pyproject.toml has [tool.ruff] with an explicit select, E501 ignored

while the formatter is in use, and a resolved target-version (or requires-python).

• Ruff pinned in dev dependencies (and optionally required-version in config).
• uv run ruff check . and uv run ruff format --check . both exit 0.
• No leftover .flake8 / .isort.cfg / [tool.black] / [tool.isort], and no

black/flake8/isort in dev dependencies (unless the documented hybrid pattern).

• Migrations: the mechanical reformat isolated in its own commit; suppressions

carry rule codes and reasons.

• scripts/check_ruff_config.py reports 0 errors.

Failure modes & gotchas

| Symptom | Cause | Fix | | --- | --- | --- | | Ruff installed but misses obvious problems | Default rules are only E+F | Write an explicit select (step 3) | | E501 violations the formatter refuses to fix | Linter and formatter both own line length | ignore = ["E501"]; the formatter wraps what it can | | Routine Ruff upgrade suddenly fails checks | select = ["ALL"] auto-enables new rules | Explicit select; pin the Ruff version | | Formatter and linter fight (commas, quotes, string concat) | COM812, ISC001, Q rules conflict with ruff format | Drop them from select/add to ignore — see conflicting rules | | --fix deletes # noqa: XY123 comments | RUF100 treats unknown codes as unused suppressions | external = ["XY"] in [tool.ruff.lint] | | Autofix emits syntax that breaks the oldest supported Python | No target-version / requires-python → py310 assumed | Set target-version to the real minimum | | Excluded files still linted when paths are passed one-by-one | Explicit file args bypass exclude (ruff#9585) | Use per-file-ignores for must-hold rules; hook-layer wiring belongs to python-precommit | | ruff check --fix exits clean, CI still red | Only safe fixes auto-apply; the rest still report | Re-run plain check; fix manually or review --unsafe-fixes --diff | | Files keep flip-flopping between formats | Black (or an IDE Black plugin) still active alongside Ruff | One formatter only — remove Black, update editor settings | | Old .flake8 / [tool.black] settings "stopped working" | Ruff never reads them | Translate into [tool.ruff], then delete the originals | | Passes locally, fails elsewhere | Version drift across dev/CI/hooks | Same pinned version everywhere; required-version makes mismatch a hard error | | Expected Ruff to format YAML/Markdown/TOML | Python-only by design; Markdown code blocks are preview-only (--preview + extend-include) | python-precommit skill covers non-Python formatting | | First CI run after adding Ruff fails hard | No local cleanup pass before wiring the gate | Run step 6 locally, commit, then gate | | ruff check green but diffs look unformatted | Lint and format are separate concerns — check doesn't verify formatting | Always run both gates (step 7) |

Bundled resources

• references/rule-selection.md — rule-prefix→origin map, tiered adoption

strategy, select vs extend-select vs ALL trade-offs, per-file-ignore conventions, isort/pydocstyle/bugbear sub-tables, fix-safety knobs.

• references/migration.md — old-command→Ruff mapping, Black/isort/Flake8 config

key translation, Flake8-plugin→prefix table, custom-plugin hybrid, incremental adoption for large legacy codebases.

• scripts/check_ruff_config.py — read-only config sanity checker; exits non-zero

on findings. Run python3 "${CLAUDE_SKILL_DIR}/scripts/check_ruff_config.py" --root (--strict to fail on warnings too).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Paldom
• Source: Paldom/python-skills
• License: MIT

Install and usage instructions live in the source repository linked above.