{"canonical_url":"https://engineer.company/glossary/ruff/","content_markdown":"# Ruff\n\n## What it is\n\nRuff is a single command-line program, written in Rust, that checks Python\nsource code against a catalogue of lint rules and rewrites its layout into one\nconsistent style. It is backed by Astral, the company behind uv and ty, and two\nof its subcommands do the daily work: `ruff check` is the linter and\n`ruff format` is the formatter. It claims to run 10 to 100 times faster than\nFlake8 and Black, keeps a cache so that unchanged files are not analysed again,\nand can stand in for Flake8 with dozens of its plugins, Black, isort,\npydocstyle, pyupgrade and autoflake.\n\nThe linter ships more than 900 rules, many of them native rewrites of popular\nFlake8 plugins. Every rule has a code made of a short prefix and three digits,\nand the prefix says where the rule came from: F401, an unused import, comes from\nPyflakes, and E501, a line that runs too long, from pycodestyle. A configuration\nselects rules by those codes, one at a time or by prefix, so\n`select = [\"E\", \"F\"]` turns on every rule whose code starts with E or F, and the\nspecial selector `ALL` turns on everything. Many rules carry a fix, sorted into\nsafe ones, meant to keep runtime behaviour, and unsafe ones, which might change\nit; `ruff check --fix` applies only the safe kind unless `--unsafe-fixes` is\npassed too.\n\nThe formatter is designed to take Black's place as a drop-in replacement. On\ncodebases such as Django and Zulip more than 99.9% of lines come out identical,\nthough the docs say plainly that the two are not meant to be swapped back and\nforth on the same code. Like Black, it skips regions fenced with `# fmt: off`\nand `# fmt: on`.\n\nBoth halves read the same configuration, which lives under `[tool.ruff]` in\n`pyproject.toml`, or in a `ruff.toml` or `.ruff.toml` file. Each Python file is\nchecked against the closest configuration file above it, and that file is used\nwhole: Ruff merges nothing from parent directories unless the nearer file names\nits parent with `extend`. Options given on the command line override every file.\nLeft unset, lines may run to 88 characters, as in Black, and the Python version\nthe rules assume is taken from the project's `requires-python` field when no\nconfiguration names one.\n\n## Why it matters\n\nSpeed decides where a check is allowed to run. A linter slow enough to interrupt\nsomeone gets pushed out to continuous integration, where it reports after the\nauthor has moved on. One that answers quickly can run in the editor and in a\ncommit hook, while the change is still fresh.\n\nConsolidation removes arguments between tools. A project that lints with Flake8\nand plugins, sorts imports with isort and formats with Black has to keep several\nconfigurations and version pins in agreement. Ruff offers one configuration, one\nversion to pin and one numbering of rules, and it publishes the list of lint\nrules that fight its own formatter, so the two can be made to agree on purpose.\n\nIts exit codes make it a gate without a wrapper. `ruff check` exits with 0 when\nthere are no violations left or every one was fixed, with 1 when violations\nremain, and with 2 when the configuration or the command line is invalid or Ruff\nitself fails, as ESLint and Prettier do. `ruff format --check` exits with 1 when\nany file would be reformatted. A rule is either selected or it is off, and any\nselected rule that fires sets the exit code to 1.\n\nThe cost is that the rule set is a decision someone has to own. Ruff's own\nadvice is to list rules explicitly with `select` rather than stacking\n`extend-select`, to start from E and F and add one group at a time, and to use\n`ALL` with discretion, because it enables new rules on every upgrade.\n\n## What it looks like in practice\n\nRuff covered Python in\n[a zero-warnings bar set across six languages](/portfolio/set-a-zero-warnings-bar-across-six-languages/),\nwhere each language had a linter of its own. Every diagnostic counted as an\nerror and inline suppressions were banned, which for Ruff rules out the `# noqa`\ncomment: a Python finding could be fixed in the code and in no other way.\nPre-commit and pre-push hooks ran the linters and the tests, so the check ran\nbefore a commit existed.\n\nAt the documented October 2026 tooling stage, this site gave Ruff a smaller job:\nthe 22 helper scripts beside the Hugo build.\nThe [credits page](/credits/) lists Ruff among the tools that keep the source\nhonest. The rule set in `pyproject.toml` is measured rather than chosen. On\n2026-10-15 every one of Ruff's 54 rule families was run against those scripts,\n39 of them reported nothing, and the silent families whose subject is this code\nwere added to the original eleven, which brings the selection to 33. The\nsecurity family, S, stays on with five rules ignored by code, each beside a\ncomment explaining why the flagged pattern here is the safe twin of a dangerous\none, so the other rules in that family still gate. Three Ruff-specific rules\nabout ambiguous Unicode characters are ignored because the site's text uses real\nem dashes, en dashes and Danish letters on purpose.\n\nThe pre-commit configuration runs `ruff check` and `ruff format --check` on any\nPython file under `scripts/` that a commit touches, and the project's fix task\nruns the same two commands in their fixing form. Beside Ruff sits basedpyright,\na type checker, with a comment that marks the boundary between them: a linter\ndoes not follow a value across a function boundary, and on its first run the\ntype checker found two real defects that Ruff had passed clean.\n\n## Where it goes wrong\n\nMost trouble with Ruff comes from a configuration that is more literal than the\npeople who wrote it.\n\n**An upgrade fails a branch nobody touched.** Code that passed yesterday reports\nnew violations after Ruff is updated. The usual cause is `select = [\"ALL\"]`,\nwhich takes on every rule a release adds, together with a version that floats.\nPin the Ruff version so that an upgrade is a reviewed commit, and list the\nfamilies the project wants instead of `ALL`, so a new family arrives only when\nsomeone adds it.\n\n**One folder stops following the project's rules.** Violations the root\nconfiguration forbids pass in a subdirectory, or a rule the team switched off\nfires there. A `ruff.toml`, or a `pyproject.toml` with a `[tool.ruff]` table,\nsits in that folder, and because Ruff uses the closest file whole, every root\nsetting stops applying below it. `ruff check --show-settings` on a file there\nprints the settings path it resolved to. Delete the nested file, or make it\ninherit with `extend = \"../pyproject.toml\"`.\n\n**A suppression outlives its reason.** A `# noqa` comment went in for a good\nreason, the code changed, and the comment now hides nothing, or the next problem\non that line. A bare `# noqa` is worse: it silences every rule on the line.\nSelect RUF100, which reports `noqa` comments that no longer suppress anything,\nand PGH004, which asks for a specific code, and let `--fix` remove the dead\nones. Here the import has since come into use, so the comment protects nothing\nand RUF100 reports it:\n\n```python\nimport json  # noqa: F401\n\nprint(json.dumps({\"ok\": True}))\n```\n\n**The formatter and the linter disagree.** `ruff format` rewrites a file and\n`ruff check` then flags the result. Some lint rules police what the formatter\ndecides, such as trailing commas (COM812), indentation (W191, E111) and quote\nstyle (the Q rules), and the formatter wraps lines to the line length only as\nfar as it can, so E501 can still fire on formatted code. Read the warnings\n`ruff format` prints, since a run free of them is the docs' own test that the\ntwo agree, ignore any rule a warning names, and treat E501 as a cue to\nrestructure the line.\n\n**A bulk fix changes behaviour.** After `ruff check --fix --unsafe-fixes` across\nthe tree, tests fail or an error handler stops catching what it used to. Unsafe\nfixes are allowed to change runtime behaviour or drop comments, and the docs'\nown example changes which exception a piece of code raises. Keep\n`--unsafe-fixes` out of hooks and scripts, apply unsafe fixes one rule at a time\nwith `--select` and read the diff, and promote a rule with `extend-safe-fixes`\nonly once the team has checked it.\n\n## Further reading\n\n- [Ruff](https://docs.astral.sh/ruff/) — what Ruff replaces, how fast it claims\n  to be and who maintains it.\n- [The Ruff Linter](https://docs.astral.sh/ruff/linter/) — rule selection and\n  precedence, safe and unsafe fixes, `noqa` comments and exit codes.\n- [The Ruff Formatter](https://docs.astral.sh/ruff/formatter/) — Black\n  compatibility and the lint rules that conflict with formatting.\n- [Rules](https://docs.astral.sh/ruff/rules/) — every rule by code, its origin\n  and whether it can be fixed.\n- [Configuring Ruff](https://docs.astral.sh/ruff/configuration/) — file\n  discovery, the closest-file rule, `extend` and the command-line options.\n\n\u003chttps://engineer.company/glossary/ruff/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"How Ruff lints and formats Python from one binary, how rules are picked by code, and why a nested config file quietly drops the project's rules.","formats":{"gemtext":"https://engineer.company/glossary/ruff/index.gmi","gopher":"https://engineer.company/glossary/ruff/gophermap","html":"https://engineer.company/glossary/ruff/","json":"https://engineer.company/glossary/ruff/index.json","markdown":"https://engineer.company/glossary/ruff/index.md","pdf":"https://engineer.company/glossary/ruff/index.pdf"},"kind":"page","language":"en","title":"What is Ruff?","url":"https://engineer.company/glossary/ruff/","version":1}