CheatPress

Ruff Python lint and format

Version 0.17.0 · source

Ruff, Postcard, light preview Light · Postcard 102 × 152 mm · PDF Ruff, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF Ruff, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
Ruff, A5, light preview Light · A5 148 × 210 mm · PDF Ruff, A5, dark preview Dark · A5 148 × 210 mm · PDF Ruff, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
Ruff, A4, light preview Light · A4 210 × 297 mm · PDF Ruff, A4, dark preview Dark · A4 210 × 297 mm · PDF Ruff, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
Ruff, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF Ruff, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF Ruff, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
Ruff, A3, light preview Light · A3 297 × 420 mm · PDF Ruff, A3, dark preview Dark · A3 297 × 420 mm · PDF Ruff, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
Ruff, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF Ruff, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF Ruff, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
Ruff, Letter, light preview Light · Letter 8.5 × 11 in · PDF Ruff, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF Ruff, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
Ruff, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF Ruff, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF Ruff, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

ruff check
Lint the project
ruff check --fix
Lint and auto-fix
ruff format
Format the project
ruff format --check
Verify formatting (CI)
ruff check --select I --fix
Sort imports
ruff rule <code>
Explain a rule
ruff check --add-noqa
Silence existing hits
ruff check --watch
Re-lint on save

Concepts

  1. Config pyproject.toml / ruff.toml
  2. ruff check violations
  3. ruff format layout
  4. Clean tree commit

Check

ruff check
Lint current directory
ruff check <path>...
Lint given files or dirs
ruff check --fix
Apply safe fixes
ruff check --diff
Preview fixes as a diff
Writes nothing; exit 0 when there is no diff.
ruff check --unsafe-fixes --fix
Also apply unsafe fixes
Unsafe fixes may change behaviour; review the diff.
ruff check --show-fixes
List what was fixed
ruff check --fix-only
Fix, do not report leftovers
ruff check --watch
Re-run on file changes
ruff check -
Lint code from stdin
ruff check --stdin-filename <name> -
Name stdin for config matching
ruff check --exit-zero
Never fail on violations
ruff check --exit-non-zero-on-fix
Fail if fixes were applied
ruff check --preview
Enable unstable rules

Format

ruff format
Format current directory
ruff format <path>...
Format given files or dirs
ruff format --check
Fail if anything would change
ruff format --diff
Show changes, write nothing
ruff format --line-length <n>
Override line length
ruff format -
Format stdin to stdout
ruff format --range <l1>-<l2> <file>
Format a line range
Range ends at the start of <l2>; 2-3 formats only line 2.
ruff format --exit-non-zero-on-format
Fail if files were rewritten
Format suppression comments
Comment Effect
# fmt: off / # fmt: on skip a region
# fmt: skip skip one statement

Rule selection

--select <codes>
Enable only these rules
Replaces the default set; codes may be prefixes like E, F, I.
--extend-select <codes>
Add rules to the current set
--ignore <codes>
Disable rules
--select ALL
Enable every rule
Noisy and changes with each release; prefer an explicit list.
--per-file-ignores <glob>:<code>
Ignore rules per path
--extend-per-file-ignores <glob>:<code>
Add per-path ignores
--fixable <codes> / --unfixable <codes>
Restrict which rules autofix
--target-version <py3xx>
Minimum Python to assume
--statistics
Count violations per rule
ruff check --select I --fix
Sort imports (isort rules)
ruff check --select UP --fix
Modernise syntax (pyupgrade)
Popular rule prefixes
Prefix From
E / W pycodestyle
F Pyflakes
I isort
B bugbear
UP pyupgrade
SIM simplify
N pep8-naming
C4 comprehensions

Suppressing

# noqa: <code>
Ignore a rule on this line
# noqa
Ignore all rules on this line
Blanket noqa hides future rules too; name the code.
# ruff: noqa: <code>
Ignore a rule for the file
ruff check --add-noqa
Insert noqa for all hits
ruff check --add-noqa="<reason>"
Insert noqa with a reason
ruff check --ignore-noqa
Report despite noqa

Explore

ruff rule <code>
Explain one rule
ruff rule --all
Explain every rule
ruff linter
List supported linters
ruff config
List all settings
ruff config <option>
Describe one setting
ruff check --show-settings <file>
Show effective settings
ruff check --show-files
List files Ruff will scan
ruff clean
Clear the cache
ruff version
Print the version

Output and files

--output-format <fmt>
Choose report format
concise, full, json, github, gitlab, sarif, junit, and more.
-o <file> / --output-file <file>
Write report to a file
--exclude <pattern>
Replace excluded paths
--extend-exclude <pattern>
Exclude more paths
--force-exclude
Honor excludes for explicit paths
Needed when a hook passes file names directly.
--no-respect-gitignore
Also scan gitignored files
--no-cache
Skip the cache
--config <file|key=value>
Use a file or override a setting
--isolated
Ignore all config files

Config

pyproject.toml basics
[tool.ruff]line-length = 100target-version = "py312"extend-exclude = ["migrations"][tool.ruff.lint]select = ["E4", "E7", "E9", "F", "I", "B"]ignore = ["B008"]
Per-file ignores
[tool.ruff.lint.per-file-ignores]"tests/**" = ["S101"]"__init__.py" = ["F401"]
Formatter options
[tool.ruff.format]quote-style = "double"indent-style = "space"docstring-code-format = true
Isort options
[tool.ruff.lint.isort]known-first-party = ["myapp"]
ruff.toml (no tool. prefix)
line-length = 100[lint]extend-select = ["I"][format]quote-style = "single"

Editors and CI

ruff server
Run the language server
pre-commit hook
repos:- repo: https://github.com/astral-sh/ruff-pre-commit  rev: <tag>  hooks:  - id: ruff-check    args: [--fix]  - id: ruff-format
GitHub Actions step
- run: pip install ruff- run: ruff check --output-format=github- run: ruff format --check

Recipes

Adopt Ruff on an old codebase
ruff check --statisticsruff check --add-noqaruff format# then tighten rules gradually
Format and fix before commit
ruff check --fixruff formatgit diff --stat
Try a rule set without editing config
ruff check --extend-select B,SIM --statisticsruff check --extend-select B --diff
CI gate
ruff check --output-format=conciseruff format --check --diff