The Ruff Linter

The Ruff Linter is the linting component of Ruff, an extremely fast Python linter and code formatter written in Rust. It is designed as a drop-in replacement for Flake8 together with dozens of its plugins, as well as isort, pydocstyle, pyupgrade and autoflake. The documentation states that Ruff can replace Flake8 when used without or with a small number of plugins, alongside Black, and on Python 3 code; under those conditions Ruff implements every rule in Flake8. That means all of the F rules originating from Pyflakes, along with a subset of the E and W rules originating from pycodestyle.

• Linting component of the Ruff CLI
• Drop-in replacement for Flake8 and many plugins
• Also replaces isort, pydocstyle, pyupgrade and autoflake
• Implements all F rules and a subset of E and W rules

`ruff check` is the primary entrypoint to the Ruff linter. It accepts a list of files or directories and lints all discovered Python files, optionally fixing any fixable errors. When linting a directory, Ruff searches for Python files recursively in that directory and all its subdirectories. The full list of supported options is available by running `ruff check --help`.

• ruff check — lint files in the current directory
• ruff check --fix — fix any fixable errors
• ruff check --watch — re-lint on change
• ruff check path/to/code/ — lint a specific path

The set of enabled rules is controlled via the lint.select, lint.extend-select and lint.ignore settings. Ruff uses Flake8-style rule codes consisting of an alphabetic prefix followed by digits, such as F401, where the prefix indicates the rule's source (F for Pyflakes, E for pycodestyle, ANN for flake8-annotations). Selectors accept either a full rule code or any valid prefix. Ruff also supports the special ALL code, which enables all rules and automatically disables conflicting pydocstyle rules such as D203 and D211.

• lint.select, lint.extend-select and lint.ignore control enabled rules
• Selectors accept full codes (F401) or prefixes (F)
• ALL enables every rule, with conflicting rules disabled
• Documentation recommends preferring select over extend-select
• Suggested starting point: select = ["E", "F"], expanding a group at a time

Ruff groups its rules into categories that describe the kind of issue each one flags. These range from outright errors to stylistic preferences, allowing users to reason about how strict a given selection will be.

• Correctness
• Suspicious
• Complexity
• Performance
• Style
• Security
• Formatting
• Pedantic

Many rules are marked fixable, and passing --fix applies those fixes automatically. The tutorial demonstrates this with an unused import: `ruff check` reports `F401 [*] \`os\` imported but unused` and notes the error is fixable, after which `ruff check --fix` removes the import. The linter documentation also covers fix safety, disabling fixes, and error suppression through inline blanket noqa comments and rule-specific noqa suppressions, configurable at line level and block level.

• --fix applies fixes for fixable rules
• Fixes carry a safety classification and can be disabled
• Inline noqa comments suppress errors at line or block level
• fixable and unfixable settings control which rules may be fixed

Ruff is configured through a pyproject.toml, ruff.toml or .ruff.toml file, and the configuration strategy and semantics are the same whether Ruff is used as a linter, a formatter, or both. Linter settings live under the [tool.ruff.lint] table in pyproject.toml or the [lint] table in ruff.toml. Ruff resolves settings for each file by looking for the first configuration file in the file's directory or any parent directory. Defaults include a line-length of 88, an indent-width of 4, a target-version of py311, fixable = ["ALL"] and an exclusion list covering commonly ignored directories.

• Config files: pyproject.toml, ruff.toml, .ruff.toml
• Linter settings under [tool.ruff.lint] or [lint]
• Default line-length 88 and indent-width 4
• Settings can also be supplied via the --config CLI flag

The Ruff linter is compatible with Black out of the box, provided the line-length setting is consistent between the two. Ruff is designed to be used alongside a formatter — either Ruff's own formatter or Black — and defers implementing stylistic rules that are obviated by automated formatting. Line-length enforcement differs slightly: Black and the Ruff formatter make a best-effort attempt to adhere to line-length but avoid automatic wrapping in some cases, while the line-too-long (E501) rule checks lines against line-length subject to documented exceptions. The limit for the linter can be overridden with lint.pycodestyle.max-line-length.

• Compatible with Black when line-length matches
• Stylistic rules obviated by formatting are deferred
• E501 can still fire under Black or ruff format
• lint.pycodestyle.max-line-length overrides the linter limit

The Ruff Language Server exposes the linter inside editors and can use an existing pyproject.toml or ruff.toml file to configure both the linter and the formatter. Settings are supplied when initialising the server; VS Code provides a user interface for them, while other editors may require manual configuration. Configuration can be given as a path to a configuration file or, since Ruff 0.9.8, as an inline JSON object. The configurationPreference setting determines precedence between editor-provided settings and project configuration files, with options for editorFirst, filesystemFirst and editorOnly.

• Ruff Language Server reads pyproject.toml or ruff.toml
• Inline JSON configuration added in Ruff 0.9.8
• configurationPreference: editorFirst, filesystemFirst, editorOnly
• Setup documented for VS Code, Neovim and Zed

The tutorial walks through adding Ruff to a Python project and running both the linter and the formatter. It initialises a project with uv, adds Ruff as a development dependency with `uv add --dev ruff`, and then runs `uv run ruff check`. As an alternative to uv run, Ruff can be run by activating the project's virtual environment and invoking `ruff check` directly. Ruff runs in the current directory by default, but specific paths can be passed on the command line.

• Add Ruff with uv add --dev ruff
• Run the linter with uv run ruff check
• Or activate the virtual environment and run ruff check
• No Rust installation is required to use Ruff