Settings
- Settings
- Top-level

Settings

Top-level

builtins

A list of builtins to treat as defined references, in addition to the system builtins.

Default value : []

Type : list[str]

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
builtins = ["_"]
``` ```
builtins = ["_"]

cache-dir

A path to the cache directory.

By default, Ruff stores cache results in a .ruff_cache directory in the current project root.

However, Ruff will also respect the RUFF_CACHE_DIR environment variable, which takes precedence over that default.

This setting will override even the RUFF_CACHE_DIR environment variable, if set.

Default value : ".ruff_cache"

Type : str

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
cache-dir = "~/.cache/ruff"
``` ```
cache-dir = "~/.cache/ruff"

exclude

A list of file patterns to exclude from formatting and linting.

Exclusions are based on globs, and can be either:

Single-path patterns, like .mypy_cache (to exclude any directory named .mypy_cache in the tree), foo.py (to exclude any file named foo.py), or foo_*.py (to exclude any file matching foo_*.py ).
Relative patterns, like directory/foo.py (to exclude that specific file) or directory/*.py (to exclude any Python files in directory). Note that these paths are relative to the project root (e.g., the directory containing your pyproject.toml).

For more information on the glob syntax, refer to the globset documentation.

Note that you’ll typically want to use extend-exclude to modify the excluded paths.

Default value : [".bzr", ".direnv", ".eggs", ".git", ".git-rewrite", ".hg", ".mypy_cache", ".nox", ".pants.d", ".pytype", ".ruff_cache", ".svn", ".tox", ".venv", "__pypackages__", "_build", "buck-out", "dist", "node_modules", "venv"]

Type : list[str]

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
exclude = [".venv"]
``` ```
exclude = [".venv"]

extend

A path to a local pyproject.toml file to merge into this configuration. User home directory and environment variables will be expanded.

To resolve the current pyproject.toml file, Ruff will first resolve this base configuration file, then merge in any properties defined in the current configuration file.

Default value : null

Type : str

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## Extend the `pyproject.toml` file in the parent directory.
extend = "../pyproject.toml"
## But use a different line length.
line-length = 100
``` ```
## Extend the `pyproject.toml` file in the parent directory.
extend = "../pyproject.toml"
## But use a different line length.
line-length = 100

extend-exclude

A list of file patterns to omit from formatting and linting, in addition to those specified by exclude.

Exclusions are based on globs, and can be either:

Single-path patterns, like .mypy_cache (to exclude any directory named .mypy_cache in the tree), foo.py (to exclude any file named foo.py), or foo_*.py (to exclude any file matching foo_*.py ).
Relative patterns, like directory/foo.py (to exclude that specific file) or directory/*.py (to exclude any Python files in directory). Note that these paths are relative to the project root (e.g., the directory containing your pyproject.toml).

For more information on the glob syntax, refer to the globset documentation.

Default value : []

Type : list[str]

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## In addition to the standard set of exclusions, omit all tests, plus a specific file.
extend-exclude = ["tests", "src/bad.py"]
``` ```
## In addition to the standard set of exclusions, omit all tests, plus a specific file.
extend-exclude = ["tests", "src/bad.py"]

extend-include

A list of file patterns to include when linting, in addition to those specified by include.

Inclusion are based on globs, and should be single-path patterns, like *.pyw, to include any file with the .pyw extension.

For more information on the glob syntax, refer to the globset documentation.

Default value : []

Type : list[str]

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## In addition to the standard set of inclusions, include `.pyw` files.
extend-include = ["*.pyw"]
``` ```
## In addition to the standard set of inclusions, include `.pyw` files.
extend-include = ["*.pyw"]

fix

Enable fix behavior by-default when running ruff (overridden by the --fix and --no-fix command-line flags). Only includes automatic fixes unless --unsafe-fixes is provided.

Default value : false

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
fix = true
``` ```
fix = true

fix-only

Like fix, but disables reporting on leftover violation. Implies fix.

Default value : false

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
fix-only = true
``` ```
fix-only = true

force-exclude

Whether to enforce exclude and extend-exclude patterns, even for paths that are passed to Ruff explicitly. Typically, Ruff will lint any paths passed in directly, even if they would typically be excluded. Setting force-exclude = true will cause Ruff to respect these exclusions unequivocally.

This is useful for pre-commit, which explicitly passes all changed files to the ruff-pre-commit plugin, regardless of whether they’re marked as excluded by Ruff’s own settings.

Default value : false

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
force-exclude = true
``` ```
force-exclude = true

include

A list of file patterns to include when linting.

Inclusion are based on globs, and should be single-path patterns, like *.pyw, to include any file with the .pyw extension. pyproject.toml is included here not for configuration but because we lint whether e.g. the [project] matches the schema.

Notebook files (.ipynb extension) are included by default on Ruff 0.6.0+.

For more information on the glob syntax, refer to the globset documentation.

Default value : ["*.py", "*.pyi", "*.ipynb", "**/pyproject.toml"]

Type : list[str]

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
include = ["*.py"]
``` ```
include = ["*.py"]

indent-width

The number of spaces per indentation level (tab).

Used by the formatter and when enforcing long-line violations (like E501) to determine the visual width of a tab.

This option changes the number of spaces the formatter inserts when using soft-tabs (indent-style = space).

PEP 8 recommends using 4 spaces per indentation level.

Default value : 4

Type : int

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
indent-width = 2
``` ```
indent-width = 2

line-length

The line length to use when enforcing long-lines violations (like E501) and at which isort and the formatter prefers to wrap lines.

The length is determined by the number of characters per line, except for lines containing East Asian characters or emojis. For these lines, the unicode width of each character is added up to determine the length.

The value must be greater than 0 and less than or equal to 320.

Note: While the formatter will attempt to format lines such that they remain within the line-length, it isn’t a hard upper bound, and formatted lines may exceed the line-length.

See pycodestyle.max-line-length to configure different lengths for E501 and the formatter.

Default value : 88

Type : int

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## Allow lines to be as long as 120.
line-length = 120
``` ```
## Allow lines to be as long as 120.
line-length = 120

namespace-packages

Mark the specified directories as namespace packages. For the purpose of module resolution, Ruff will treat those directories and all their subdirectories as if they contained an __init__.py file.

Default value : []

Type : list[str]

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
namespace-packages = ["airflow/providers"]
``` ```
namespace-packages = ["airflow/providers"]

output-format

The style in which violation messages should be formatted: "full" (default) (shows source), "concise", "grouped" (group messages by file), "json" (machine-readable), "junit" (machine-readable XML), "github" (GitHub Actions annotations), "gitlab" (GitLab CI code quality report), "pylint" (Pylint text format) or "azure" (Azure Pipeline logging commands).

Default value : "full"

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## Group violations by containing file.
output-format = "grouped"
``` ```
## Group violations by containing file.
output-format = "grouped"

per-file-target-version

A list of mappings from glob-style file pattern to Python version to use when checking the corresponding file(s).

This may be useful for overriding the global Python version settings in target-version or requires-python for a subset of files. For example, if you have a project with a minimum supported Python version of 3.9 but a subdirectory of developer scripts that want to use a newer feature like the match statement from Python 3.10, you can use per-file-target-version to specify "developer_scripts/*.py" = "py310".

This setting is used by the linter to enforce any enabled version-specific lint rules, as well as by the formatter for any version-specific formatting options, such as parenthesizing context managers on Python 3.10+.

Default value : {}

Type : dict[str, PythonVersion]

Example usage :

pyproject.tomlruff.toml

[tool.ruff.per-file-target-version]
## Override the project-wide Python version for a developer scripts directory:
"scripts/**.py" = "py312"
``` ```
[per-file-target-version]
## Override the project-wide Python version for a developer scripts directory:
"scripts/**.py" = "py312"

preview

Whether to enable preview mode. When preview mode is enabled, Ruff will use unstable rules, fixes, and formatting.

Default value : false

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## Enable preview features.
preview = true
``` ```
## Enable preview features.
preview = true

required-version

Enforce a requirement on the version of Ruff, to enforce at runtime. If the version of Ruff does not meet the requirement, Ruff will exit with an error.

Useful for unifying results across many environments, e.g., with a pyproject.toml file.

Accepts a PEP 440 specifier, like ==0.3.1 or >=0.3.1.

Default value : null

Type : str

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
required-version = ">=0.0.193"
``` ```
required-version = ">=0.0.193"

respect-gitignore

Whether to automatically exclude files that are ignored by .ignore, .gitignore, .git/info/exclude, and global gitignore files. Enabled by default.

Default value : true

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
respect-gitignore = false
``` ```
respect-gitignore = false

show-fixes

Whether to show an enumeration of all fixed lint violations (overridden by the --show-fixes command-line flag).

Default value : false

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## Enumerate all fixed violations.
show-fixes = true
``` ```
## Enumerate all fixed violations.
show-fixes = true

src

The directories to consider when resolving first- vs. third-party imports.

When omitted, the src directory will typically default to including both:

The directory containing the nearest pyproject.toml, ruff.toml, or .ruff.toml file (the “project root”).
The "src" subdirectory of the project root.

These defaults ensure that Ruff supports both flat layouts and src layouts out-of-the-box. (If a configuration file is explicitly provided (e.g., via the --config command-line flag), the current working directory will be considered the project root.)

As an example, consider an alternative project structure, like:

my_project
├── pyproject.toml
└── lib
    └── my_package
        ├── __init__.py
        ├── foo.py
        └── bar.py

In this case, the ./lib directory should be included in the src option (e.g., src = ["lib"]), such that when resolving imports, my_package.foo is considered first-party.

This field supports globs. For example, if you have a series of Python packages in a python_modules directory, src = ["python_modules/*"] would expand to incorporate all packages in that directory. User home directory and environment variables will also be expanded.

Default value : [".", "src"]

Type : list[str]

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## Allow imports relative to the "src" and "test" directories.
src = ["src", "test"]
``` ```
## Allow imports relative to the "src" and "test" directories.
src = ["src", "test"]

target-version

The minimum Python version to target, e.g., when considering automatic code upgrades, like rewriting type annotations. Ruff will not propose changes using features that are not available in the given version.

For example, to represent supporting Python >=3.10 or ==3.10 specify target-version = "py310".

If you’re already using a pyproject.toml file, we recommend project.requires-python instead, as it’s based on Python packaging standards, and will be respected by other tools. For example, Ruff treats the following as identical to target-version = "py38":

[project]
requires-python = ">=3.8"

If both are specified, target-version takes precedence over requires-python. See Inferring the Python version for a complete description of how the target-version is determined when left unspecified.

Note that a stub file can sometimes make use of a typing feature before it is available at runtime, as long as the stub does not make use of new syntax. For example, a type checker will understand int | str in a stub as being a Union type annotation, even if the type checker is run using Python 3.9, despite the fact that the | operator can only be used to create union types at runtime on Python 3.10+. As such, Ruff will often recommend newer features in a stub file than it would for an equivalent runtime file with the same target version.

Default value : "py39"

Type : "py37" | "py38" | "py39" | "py310" | "py311" | "py312" | "py313"

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
## Always generate Python 3.7-compatible code.
target-version = "py37"
``` ```
## Always generate Python 3.7-compatible code.
target-version = "py37"

unsafe-fixes

Enable application of unsafe fixes. If excluded, a hint will be displayed when unsafe fixes are available. If set to false, the hint will be hidden.

Default value : null

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff]
unsafe-fixes = true
``` ```
unsafe-fixes = true

analyze

Configures Ruff’s analyze command.

detect-string-imports

Whether to detect imports from string literals. When enabled, Ruff will search for string literals that “look like” import paths, and include them in the import map, if they resolve to valid Python modules.

Default value : false

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff.analyze]
detect-string-imports = true
``` ```
[analyze]
detect-string-imports = true

direction

Whether to generate a map from file to files that it depends on (dependencies) or files that depend on it (dependents).

Default value : "dependencies"

Type : "dependents" | "dependencies"

Example usage :

pyproject.tomlruff.toml

[tool.ruff.analyze]
direction = "dependencies"
``` ```
[analyze]
direction = "dependencies"

exclude

A list of file patterns to exclude from analysis in addition to the files excluded globally (see exclude, and extend-exclude).

Exclusions are based on globs, and can be either:

Single-path patterns, like .mypy_cache (to exclude any directory named .mypy_cache in the tree), foo.py (to exclude any file named foo.py), or foo_*.py (to exclude any file matching foo_*.py ).
Relative patterns, like directory/foo.py (to exclude that specific file) or directory/*.py (to exclude any Python files in directory). Note that these paths are relative to the project root (e.g., the directory containing your pyproject.toml).

For more information on the glob syntax, refer to the globset documentation.

Default value : []

Type : list[str]

Example usage :

pyproject.tomlruff.toml

[tool.ruff.analyze]
exclude = ["generated"]
``` ```
[analyze]
exclude = ["generated"]

include-dependencies

A map from file path to the list of Python or non-Python file paths or globs that should be considered dependencies of that file, regardless of whether relevant imports are detected.

Default value : {}

Type : dict[str, list[str]]

Example usage :

pyproject.tomlruff.toml

[tool.ruff.analyze.include-dependencies]
"foo/bar.py" = ["foo/baz/*.py"]
"foo/baz/reader.py" = ["configs/bar.json"]
``` ```
[analyze.include-dependencies]
"foo/bar.py" = ["foo/baz/*.py"]
"foo/baz/reader.py" = ["configs/bar.json"]

preview

Whether to enable preview mode. When preview mode is enabled, Ruff will expose unstable commands.

Default value : false

Type : bool

Example usage :

pyproject.tomlruff.toml

[tool.ruff.analyze]
## Enable preview features.
preview = true
``` ```
[analyze]
## Enable preview features.
preview = true

format

Configures the way Ruff formats your code.

docstring-code-format

Whether to format code snippets in docstrings.

When this is enabled, Python code examples within docstrings are automatically reformatted.

For example, when this is enabled, the following code:

def f(x):
    """
    Something about `f`. And an example in doctest format:

    >>> f(  x  )

    Markdown is also supported:

    ```py
    f(  x  )
``` ```
As are reStructuredText literal blocks::

    f(  x  )

And reStructuredText code blocks:

.. code-block:: python

    f(  x  )
"""
pass
``` ```

... will be reformatted (assuming the rest of the options are set to their defaults) as:

def f(x): “”” Something about f. And an example in doctest format:

>>> f(x)

Markdown is also supported:

```py
f(x)

As are reStructuredText literal blocks::

f(x)

And reStructuredText code blocks:

.. code-block:: python

f(x)

""" pass

If a code snippet in a docstring contains invalid Python code or if the formatter would otherwise write invalid Python code, then the code example is ignored by the formatter and kept as-is.

Currently, doctest, Markdown, reStructuredText literal blocks, and reStructuredText code blocks are all supported and automatically recognized. In the case of unlabeled fenced code blocks in Markdown and reStructuredText literal blocks, the contents are assumed to be Python and reformatted. As with any other format, if the contents aren't valid Python, then the block is left untouched automatically.

Default value: false

Type: bool

Example usage:

pyproject.tomlruff.toml


[tool.ruff.format]

## Enable reformatting of code snippets in docstrings.

docstring-code-format = true


[format]

## Enable reformatting of code snippets in docstrings.

docstring-code-format = true

docstring-code-line-length

Set the line length used when formatting code snippets in docstrings.

This only has an effect when the docstring-code-format setting is enabled.

The default value for this setting is "dynamic", which has the effect of ensuring that any reformatted code examples in docstrings adhere to the global line length configuration that is used for the surrounding Python code. The point of this setting is that it takes the indentation of the docstring into account when reformatting code examples.

Alternatively, this can be set to a fixed integer, which will result in the same line length limit being applied to all reformatted code examples in docstrings. When set to a fixed integer, the indent of the docstring is not taken into account. That is, this may result in lines in the reformatted code example that exceed the globally configured line length limit.

For example, when this is set to 20 and docstring-code-format is enabled, then this code:


def f(x): ‘’’ Something about `f`. And an example:

.. code-block:: python

foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)

''' pass

... will be reformatted (assuming the rest of the options are set to their defaults) as:


def f(x): “”” Something about `f`. And an example:

.. code-block:: python

(
    foo,
    bar,
    quux,
) = this_is_a_long_line(
    lion,
    hippo,
    lemur,
    bear,
)

""" pass

Default value: "dynamic"

Type: int | "dynamic"

Example usage:

pyproject.tomlruff.toml


[tool.ruff.format]

## Format all docstring code snippets with a line length of 60.

docstring-code-line-length = 60


[format]

## Format all docstring code snippets with a line length of 60.

docstring-code-line-length = 60

exclude

A list of file patterns to exclude from formatting in addition to the files excluded globally (see exclude, and extend-exclude).

Exclusions are based on globs, and can be either:

Single-path patterns, like .mypy_cache (to exclude any directory named .mypy_cache in the tree), foo.py (to exclude any file named foo.py), or foo_*.py (to exclude any file matching foo_*.py ).
Relative patterns, like directory/foo.py (to exclude that specific file) or directory/*.py (to exclude any Python files in directory). Note that these paths are relative to the project root (e.g., the directory containing your pyproject.toml).

For more information on the glob syntax, refer to the globset documentation.

Default value: []

Type: list[str]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.format] exclude = [“generated”]


[format] exclude = [“generated”]

indent-style

Whether to use spaces or tabs for indentation.

indent-style = "space" (default):


def f(): print(“Hello”) # Spaces indent the `print` statement.

indent-style = "tab":


def f(): print(“Hello”) # A tab `\t` indents the `print` statement.

PEP 8 recommends using spaces for indentation. We care about accessibility; if you do not need tabs for accessibility, we do not recommend you use them.

See indent-width to configure the number of spaces per indentation and the tab width.

Default value: "space"

Type: "space" | "tab"

Example usage:

pyproject.tomlruff.toml


[tool.ruff.format]

## Use tabs instead of 4 space indentation.

indent-style = “tab”


[format]

## Use tabs instead of 4 space indentation.

indent-style = “tab”

line-ending

The character Ruff uses at the end of a line.

auto: The newline style is detected automatically on a file per file basis. Files with mixed line endings will be converted to the first detected line ending. Defaults to \n for files that contain no line endings.
lf: Line endings will be converted to \n. The default line ending on Unix.
cr-lf: Line endings will be converted to \r\n. The default line ending on Windows.
native: Line endings will be converted to \n on Unix and \r\n on Windows.

Default value: "auto"

Type: "auto" | "lf" | "cr-lf" | "native"

Example usage:

pyproject.tomlruff.toml


[tool.ruff.format]

## Use `\n` line endings for all files

line-ending = “lf”


[format]

## Use `\n` line endings for all files

line-ending = “lf”

preview

Whether to enable the unstable preview style formatting.

Default value: false

Type: bool

Example usage:

pyproject.tomlruff.toml


[tool.ruff.format]

## Enable preview style formatting.

preview = true


[format]

## Enable preview style formatting.

preview = true

quote-style

Configures the preferred quote character for strings. The recommended options are

double (default): Use double quotes "
single: Use single quotes '

In compliance with PEP 8 and PEP 257, Ruff prefers double quotes for triple quoted strings and docstrings even when using quote-style = "single".

Ruff deviates from using the configured quotes if doing so prevents the need for escaping quote characters inside the string:


a = “a string without any quotes” b = “It’s monday morning”

Ruff will change the quotes of the string assigned to a to single quotes when using quote-style = "single". However, Ruff uses double quotes for the string assigned to b because using single quotes would require escaping the ', which leads to the less readable code: 'It\'s monday morning'.

In addition, Ruff supports the quote style preserve for projects that already use a mixture of single and double quotes and can't migrate to the double or single style. The quote style preserve leaves the quotes of all strings unchanged.

Default value: "double"

Type: "double" | "single" | "preserve"

Example usage:

pyproject.tomlruff.toml


[tool.ruff.format]

## Prefer single quotes over double quotes.

quote-style = “single”


[format]

## Prefer single quotes over double quotes.

quote-style = “single”

skip-magic-trailing-comma

Ruff uses existing trailing commas as an indication that short lines should be left separate. If this option is set to true, the magic trailing comma is ignored.

For example, Ruff leaves the arguments separate even though collapsing the arguments to a single line doesn't exceed the line length if skip-magic-trailing-comma = false:


## The arguments remain on separate lines because of the trailing comma after `b`

def test( a, b, ): pass

Setting skip-magic-trailing-comma = true changes the formatting to:


## The arguments remain on separate lines because of the trailing comma after `b`

def test(a, b): pass

Default value: false

Type: bool

Example usage:

pyproject.tomlruff.toml


[tool.ruff.format] skip-magic-trailing-comma = true


[format] skip-magic-trailing-comma = true

lint

Configures how Ruff checks your code.

Options specified in the lint section take precedence over the deprecated top-level settings.

allowed-confusables

A list of allowed "confusable" Unicode characters to ignore when enforcing RUF001, RUF002, and RUF003.

Default value: []

Type: list[str]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Allow minus-sign (U+2212), greek-small-letter-rho (U+03C1), and the asterisk-operator (U+2217),

## which could be confused for “-“, “p”, and “*”, respectively.

allowed-confusables = [“−”, “ρ”, “∗”]


[lint]

## Allow minus-sign (U+2212), greek-small-letter-rho (U+03C1), and the asterisk-operator (U+2217),

## which could be confused for “-“, “p”, and “*”, respectively.

allowed-confusables = [“−”, “ρ”, “∗”]

dummy-variable-rgx

A regular expression used to identify "dummy" variables, or those which should be ignored when enforcing (e.g.) unused-variable rules. The default expression matches _, __, and _var, but not _var_.

Default value: "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

Type: str

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Only ignore variables named “_”.

dummy-variable-rgx = “^_$”


[lint]

## Only ignore variables named “_”.

dummy-variable-rgx = “^_$”

exclude

A list of file patterns to exclude from linting in addition to the files excluded globally (see exclude, and extend-exclude).

Exclusions are based on globs, and can be either:

Single-path patterns, like .mypy_cache (to exclude any directory named .mypy_cache in the tree), foo.py (to exclude any file named foo.py), or foo_*.py (to exclude any file matching foo_*.py ).
Relative patterns, like directory/foo.py (to exclude that specific file) or directory/*.py (to exclude any Python files in directory). Note that these paths are relative to the project root (e.g., the directory containing your pyproject.toml).

For more information on the glob syntax, refer to the globset documentation.

Default value: []

Type: list[str]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint] exclude = [“generated”]


[lint] exclude = [“generated”]

explicit-preview-rules

Whether to require exact codes to select preview rules. When enabled, preview rules will not be selected by prefixes — the full code of each preview rule will be required to enable the rule.

Default value: false

Type: bool

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Require explicit selection of preview rules.

explicit-preview-rules = true


[lint]

## Require explicit selection of preview rules.

explicit-preview-rules = true

extend-fixable

A list of rule codes or prefixes to consider fixable, in addition to those specified by fixable.

Default value: []

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Enable fix for flake8-bugbear (`B`), on top of any rules specified by `fixable`.

extend-fixable = [“B”]


[lint]

## Enable fix for flake8-bugbear (`B`), on top of any rules specified by `fixable`.

extend-fixable = [“B”]

extend-ignore

Deprecated

This option has been deprecated. The extend-ignore option is now interchangeable with ignore. Please update your configuration to use the ignore option instead.

A list of rule codes or prefixes to ignore, in addition to those specified by ignore.

Default value: []

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Skip unused variable rules (`F841`).

extend-ignore = [“F841”]


[lint]

## Skip unused variable rules (`F841`).

extend-ignore = [“F841”]

extend-per-file-ignores

A list of mappings from file pattern to rule codes or prefixes to exclude, in addition to any rules excluded by per-file-ignores.

Default value: {}

Type: dict[str, list[RuleSelector]]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint.extend-per-file-ignores]

## Also ignore `E402` in all `__init__.py` files.

“**init**.py” = [“E402”]


[lint.extend-per-file-ignores]

## Also ignore `E402` in all `__init__.py` files.

“**init**.py” = [“E402”]

extend-safe-fixes

A list of rule codes or prefixes for which unsafe fixes should be considered safe.

Default value: []

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Allow applying all unsafe fixes in the `E` rules and `F401` without the `--unsafe-fixes` flag

extend-safe-fixes = [“E”, “F401”]


[lint]

## Allow applying all unsafe fixes in the `E` rules and `F401` without the `--unsafe-fixes` flag

extend-safe-fixes = [“E”, “F401”]

extend-select

A list of rule codes or prefixes to enable, in addition to those specified by select.

Default value: []

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## On top of the default `select` (`E4`, E7`,`E9`, and`F`), enable flake8-bugbear (`B`) and flake8-quotes (`Q`).

extend-select = [“B”, “Q”]


[lint]

## On top of the default `select` (`E4`, E7`,`E9`, and`F`), enable flake8-bugbear (`B`) and flake8-quotes (`Q`).

extend-select = [“B”, “Q”]

extend-unsafe-fixes

A list of rule codes or prefixes for which safe fixes should be considered unsafe.

Default value: []

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Require the `--unsafe-fixes` flag when fixing the `E` rules and `F401`

extend-unsafe-fixes = [“E”, “F401”]


[lint]

## Require the `--unsafe-fixes` flag when fixing the `E` rules and `F401`

extend-unsafe-fixes = [“E”, “F401”]

external

A list of rule codes or prefixes that are unsupported by Ruff, but should be preserved when (e.g.) validating # noqa directives. Useful for retaining # noqa directives that cover plugins not yet implemented by Ruff.

Default value: []

Type: list[str]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Avoiding flagging (and removing) any codes starting with `V` from any

## `# noqa` directives, despite Ruff’s lack of support for `vulture`.

external = [“V”]


[lint]

## Avoiding flagging (and removing) any codes starting with `V` from any

## `# noqa` directives, despite Ruff’s lack of support for `vulture`.

external = [“V”]

fixable

A list of rule codes or prefixes to consider fixable. By default, all rules are considered fixable.

Default value: ["ALL"]

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Only allow fix behavior for `E` and `F` rules.

fixable = [“E”, “F”]


[lint]

## Only allow fix behavior for `E` and `F` rules.

fixable = [“E”, “F”]

ignore

A list of rule codes or prefixes to ignore. Prefixes can specify exact rules (like F841), entire categories (like F), or anything in between.

When breaking ties between enabled and disabled rules (via select and ignore, respectively), more specific prefixes override less specific prefixes. ignore takes precedence over select if the same prefix appears in both.

Default value: []

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Skip unused variable rules (`F841`).

ignore = [“F841”]


[lint]

## Skip unused variable rules (`F841`).

ignore = [“F841”]

ignore-init-module-imports

Deprecated

This option has been deprecated in 0.4.4. ignore-init-module-imports will be removed in a future version because F401 now recommends appropriate fixes for unused imports in __init__.py (currently in preview mode). See documentation for more information and please update your configuration.

Avoid automatically removing unused imports in __init__.py files. Such imports will still be flagged, but with a dedicated message suggesting that the import is either added to the module's __all__ symbol, or re-exported with a redundant alias (e.g., import os as os).

This option is enabled by default, but you can opt-in to removal of imports via an unsafe fix.

Default value: true

Type: bool

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint] ignore-init-module-imports = false


[lint] ignore-init-module-imports = false

logger-objects

A list of objects that should be treated equivalently to a logging.Logger object.

This is useful for ensuring proper diagnostics (e.g., to identify logging deprecations and other best-practices) for projects that re-export a logging.Logger object from a common module.

For example, if you have a module logging_setup.py with the following contents:


import logging

logger = logging.getLogger(**name**)

Adding "logging_setup.logger" to logger-objects will ensure that logging_setup.logger is treated as a logging.Logger object when imported from other modules (e.g., from logging_setup import logger).

Default value: []

Type: list[str]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint] logger-objects = [“logging_setup.logger”]


[lint] logger-objects = [“logging_setup.logger”]

per-file-ignores

A list of mappings from file pattern to rule codes or prefixes to exclude, when considering any matching files. An initial '!' negates the file pattern.

Default value: {}

Type: dict[str, list[RuleSelector]]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint.per-file-ignores]

## Ignore `E402` (import violations) in all `__init__.py` files, and in `path/to/file.py`.

“**init**.py” = [“E402”] “path/to/file.py” = [“E402”]

## Ignore `D` rules everywhere except for the `src/` directory.

“!src/**.py” = [“D”]


[lint.per-file-ignores]

## Ignore `E402` (import violations) in all `__init__.py` files, and in `path/to/file.py`.

“**init**.py” = [“E402”] “path/to/file.py” = [“E402”]

## Ignore `D` rules everywhere except for the `src/` directory.

“!src/**.py” = [“D”]

preview

Whether to enable preview mode. When preview mode is enabled, Ruff will use unstable rules and fixes.

Default value: false

Type: bool

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Enable preview features.

preview = true


[lint]

## Enable preview features.

preview = true

select

A list of rule codes or prefixes to enable. Prefixes can specify exact rules (like F841), entire categories (like F), or anything in between.

Default value: ["E4", "E7", "E9", "F"]

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## On top of the defaults (`E4`, E7`,`E9`, and`F`), enable flake8-bugbear (`B`) and flake8-quotes (`Q`).

select = [“E4”, “E7”, “E9”, “F”, “B”, “Q”]


[lint]

## On top of the defaults (`E4`, E7`,`E9`, and`F`), enable flake8-bugbear (`B`) and flake8-quotes (`Q`).

select = [“E4”, “E7”, “E9”, “F”, “B”, “Q”]

task-tags

A list of task tags to recognize (e.g., "TODO", "FIXME", "XXX").

Comments starting with these tags will be ignored by commented-out code detection (ERA), and skipped by line-length rules (E501) if ignore-overlong-task-comments is set to true.

Default value: ["TODO", "FIXME", "XXX"]

Type: list[str]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint] task-tags = [“HACK”]


[lint] task-tags = [“HACK”]

typing-extensions

Whether to allow imports from the third-party typing_extensions module for Python versions before a symbol was added to the first-party typing module.

Many rules try to import symbols from the typing module but fall back to typing_extensions for earlier versions of Python. This option can be used to disable this fallback behavior in cases where typing_extensions is not installed.

Default value: true

Type: bool

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Disable `typing_extensions` imports

typing-extensions = false


[lint]

## Disable `typing_extensions` imports

typing-extensions = false

typing-modules

A list of modules whose exports should be treated equivalently to members of the typing module.

This is useful for ensuring proper type annotation inference for projects that re-export typing and typing_extensions members from a compatibility module. If omitted, any members imported from modules apart from typing and typing_extensions will be treated as ordinary Python objects.

Default value: []

Type: list[str]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint] typing-modules = [“airflow.typing_compat”]


[lint] typing-modules = [“airflow.typing_compat”]

unfixable

A list of rule codes or prefixes to consider non-fixable.

Default value: []

Type: list[RuleSelector]

Example usage:

pyproject.tomlruff.toml


[tool.ruff.lint]

## Disable fix for unused imports (`F401`).

unfixable = [“F401”]


[lint]

## Disable fix for unused imports (`F401`).

unfixable = [“F401”]

（本文超出站点单文档体积上限，已按小节截断）