latest--ruff

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.

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

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.

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.

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

The minimum number of dots in a string to consider it a valid import.

This setting is only relevant when detect-string-imports is enabled. For example, if this is set to 2, then only strings with at least two dots (e.g., "path.to.module") would be considered valid imports.

Whether to include imports that are only used for type checking (i.e., imports within if TYPE_CHECKING: blocks). When enabled (default), type-checking-only imports are included in the import graph. When disabled, they are excluded.

The message to display when the API is used.

Whether to suppress ANN401 for dynamically typed *args and **kwargs arguments.

Whether to suppress ANN* rules for any declaration that hasn't been typed at all. This makes it easier to gradually add types to a codebase.

Whether to allow the omission of a return type hint for __init__ if at least one argument is annotated.

Whether to suppress ANN000-level violations for arguments matching the "dummy" variable regex (like _).

Whether to suppress ANN200-level violations for functions that meet either of the following criteria:

• Contain no return statement.
• Explicit return statement(s) all return None (explicitly or implicitly).

A list of callable names, whose result may be safely passed into markupsafe.Markup.

Expects to receive a list of fully-qualified names (e.g., bleach.clean, rather than clean).

This setting helps you avoid false positives in code like:

from bleach import clean
from markupsafe import Markup

cleaned_markup = Markup(clean(some_user_input))

Where the use of bleach.clean usually ensures that there's no XSS vulnerability.

Although it is not recommended, you may also use this setting to whitelist other kinds of calls, e.g. calls to i18n translation functions, where how safe that is will depend on the implementation and how well the translations are audited.

Another common use-case is to wrap the output of functions that generate markup like xml.etree.ElementTree.tostring or template rendering engines where sanitization of potential user input is either already baked in or has to happen before rendering.

Whether to disallow try-except-pass (S110) for specific exception types. By default, try-except-pass is only disallowed for Exception and BaseException.

A list of additional callable names that behave like markupsafe.Markup.

Expects to receive a list of fully-qualified names (e.g., webhelpers.html.literal, rather than literal).

A list of directories to consider temporary (see S108).

A list of directories to consider temporary, in addition to those specified by hardcoded-tmp-directory (see S108).

Additional callable functions with which to allow boolean traps.

Expects to receive a list of fully-qualified names (e.g., pydantic.Field, rather than Field).

Additional callable functions to consider "immutable" when evaluating, e.g., the function-call-in-default-argument rule (B008) or function-call-in-dataclass-defaults rule (RUF009).

Expects to receive a list of fully-qualified names (e.g., fastapi.Query, rather than Query).

List of builtin module names to allow.

DEPRECATED: This option has been renamed to allowed-modules. Use allowed-modules instead.

List of builtin module names to allow.

This option is ignored if both allowed-modules and builtins-allowed-modules are set.

DEPRECATED: This option has been renamed to ignorelist. Use ignorelist instead.

Ignore list of builtins.

This option is ignored if both ignorelist and builtins-ignorelist are set.

DEPRECATED: This option has been renamed to strict-checking. Use strict-checking instead.

Compare module names instead of full module paths.

This option is ignored if both strict-checking and builtins-strict-checking are set.

Ignore list of builtins.

Compare module names instead of full module paths.

Used by A005 - stdlib-module-shadowing.

Allow dict calls that make use of keyword arguments (e.g., dict(a=1, b=2)).

Author to enforce within the copyright notice. If provided, the author must be present immediately following the copyright notice.

A minimum file size (in bytes) required for a copyright notice to be enforced. By default, all files are validated.

The regular expression used to match the copyright notice, compiled with the regex crate. Defaults to (?i)Copyright\s+((?:\(C\)|©)\s+)?\d{4}((-|,\s)\d{4})*, which matches the following:

• Copyright 2023
• Copyright (C) 2023
• Copyright 2021-2023
• Copyright (C) 2021-2023
• Copyright (C) 2021, 2023

Maximum string length for string literals in exception messages.

Additional function names to consider as internationalization calls, in addition to those included in function-names.

The function names to consider as internationalization calls.

Whether to allow implicit string concatenations for multiline strings. By default, implicit concatenations of multiline strings are allowed (but continuation lines, delimited with a backslash, are prohibited).

Setting allow-multiline = false will automatically disable the explicit-string-concatenation (ISC003) rule. Otherwise, both implicit and explicit multiline string concatenations would be seen as violations, making it impossible to write a linter-compliant multiline string.

The conventional aliases for imports. These aliases can be extended by the extend-aliases option.

A mapping from module to its banned import aliases.

A list of modules that should not be imported from using the from ... import ... syntax.

For example, given banned-from = ["pandas"], from pandas import DataFrame would be disallowed, while import pandas would be allowed.

A mapping from module to conventional import alias. These aliases will be added to the aliases mapping.

Boolean flag specifying whether @pytest.fixture() without parameters should have parentheses. If the option is set to false (the default), @pytest.fixture is valid and @pytest.fixture() is invalid. If set to true, @pytest.fixture() is valid and @pytest.fixture is invalid.

Boolean flag specifying whether @pytest.mark.foo() without parameters should have parentheses. If the option is set to false (the default), @pytest.mark.foo is valid and @pytest.mark.foo() is invalid. If set to true, @pytest.mark.foo() is valid and @pytest.mark.foo is invalid.

Expected type for multiple argument names in @pytest.mark.parametrize. The following values are supported:

• csv — a comma-separated list, e.g. @pytest.mark.parametrize("name1,name2", ...)
• tuple (default) — e.g. @pytest.mark.parametrize(("name1", "name2"), ...)
• list — e.g. @pytest.mark.parametrize(["name1", "name2"], ...)

Expected type for each row of values in @pytest.mark.parametrize in case of multiple parameters. The following values are supported:

• tuple (default) — e.g. @pytest.mark.parametrize(("name1", "name2"), [(1, 2), (3, 4)])
• list — e.g. @pytest.mark.parametrize(("name1", "name2"), [[1, 2], [3, 4]])

Expected type for the list of values rows in @pytest.mark.parametrize. The following values are supported:

• tuple — e.g. @pytest.mark.parametrize("name", (1, 2, 3))
• list (default) — e.g. @pytest.mark.parametrize("name", [1, 2, 3])

List of additional exception names that require a match= parameter in a pytest.raises() call. This extends the default list of exceptions that require a match= parameter. This option is useful if you want to extend the default list of exceptions that require a match= parameter without having to specify the entire list. Note that this option does not remove any exceptions from the default list.

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

List of exception names that require a match= parameter in a pytest.raises() call.

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

List of additional warning names that require a match= parameter in a pytest.warns() call. This extends the default list of warnings that require a match= parameter.

This option is useful if you want to extend the default list of warnings that require a match= parameter without having to specify the entire list.

Note that this option does not remove any warnings from the default list.

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

List of warning names that require a match= parameter in a pytest.warns() call.

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

Whether to avoid using single quotes if a string contains single quotes, or vice-versa with double quotes, as per PEP 8. This minimizes the need to escape quotation marks within strings.

Quote style to prefer for docstrings (either "single" or "double").

When using the formatter, only "double" is compatible, as the formatter enforces double quotes for docstrings strings.

Quote style to prefer for inline strings (either "single" or "double").

When using the formatter, ensure that format.quote-style is set to the same preferred quote style.

Quote style to prefer for multiline strings (either "single" or "double").

When using the formatter, only "double" is compatible, as the formatter enforces double quotes for multiline strings.

Additional names to ignore when considering flake8-self violations, in addition to those included in ignore-names.

A list of names to ignore when considering flake8-self violations.

Specific modules that may not be imported lazily, or "all" to forbid lazy imports except for any modules excluded from the selector. This rule is only enforced when targeting Python 3.15 or newer.

Whether to ban all relative imports ("all"), or only those imports that extend into the parent module or beyond ("parents").

Specific modules or module members that may not be imported or accessed. Note that this rule is only meant to flag accidental uses, and can be circumvented via eval or importlib.

List of specific modules that may not be imported at module level, and should instead be imported lazily (e.g., within a function definition, or an if TYPE_CHECKING: block, or some other nested context). This also affects the rule import-outside-top-level if banned-module-level-imports is enabled.

Specific modules that must be imported lazily in contexts where lazy import is legal, or "all" to require every lazily-convertible import to use the lazy keyword. Ruff ignores contexts where lazy import is invalid, such as functions, classes, try/except blocks, __future__ imports, and from ... import * statements. This rule is only enforced when targeting Python 3.15 or newer.

Exempt certain modules from needing to be moved into type-checking blocks.

Whether to add quotes around type annotations, if doing so would allow the corresponding import to be moved into a type-checking block.

For example, in the following, Python requires that Sequence be available at runtime, despite the fact that it's only used in a type annotation:

from collections.abc import Sequence


def func(value: Sequence[int]) -> None:
    ...

In other words, moving from collections.abc import Sequence into an if TYPE_CHECKING: block above would cause a runtime error, as the type would no longer be available at runtime.

By default, Ruff will respect such runtime semantics and avoid moving the import to prevent such runtime errors.

Setting quote-annotations to true will instruct Ruff to add quotes around the annotation (e.g., "Sequence[int]"), which in turn enables Ruff to move the import into an if TYPE_CHECKING: block, like so:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from collections.abc import Sequence


def func(value: "Sequence[int]") -> None:
    ...

Note that this setting has no effect when from __future__ import annotations is present, as __future__ annotations are always treated equivalently to quoted annotations. Similarly, this setting has no effect on Python versions after 3.14 because these annotations are also deferred.

Exempt classes that list any of the enumerated classes as a base class from needing to be moved into type-checking blocks.

Common examples include Pydantic's pydantic.BaseModel and SQLAlchemy's sqlalchemy.orm.DeclarativeBase, but can also support user-defined classes that inherit from those base classes. For example, if you define a common DeclarativeBase subclass that's used throughout your project (e.g., class Base(DeclarativeBase) ... in base.py), you can add it to this list (runtime-evaluated-base-classes = ["base.Base"]) to exempt models from being moved into type-checking blocks.

Exempt classes and functions decorated with any of the enumerated decorators from being moved into type-checking blocks.

Common examples include Pydantic's @pydantic.validate_call decorator (for functions) and attrs' @attrs.define decorator (for classes).

This also supports framework decorators like FastAPI's fastapi.FastAPI.get which will work across assignments in the same module.

For example:

from fastapi import FastAPI

app = FastAPI("app")

@app.get("/home")
def home() -> str: ...

Here app.get will correctly be identified as fastapi.FastAPI.get.

Enforce TC001, TC002, and TC003 rules even when valid runtime imports are present for the same module.

See flake8-type-checking's strict option.

Whether to allow unused variadic arguments, like *args and **kwargs.

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.

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

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.

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.

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.

Whether to enable the unstable preview style formatting.

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.

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 are collapsed to a single line because the trailing comma is ignored
def test(a, b):
    pass

Sort imports taking into account case sensitivity.

Note that the order-by-type setting will take precedence over this one when enabled.

An override list of tokens to always recognize as a Class for order-by-type regardless of casing.

Combines as imports on the same line. See isort's combine-as-imports option.

An override list of tokens to always recognize as a CONSTANT for order-by-type regardless of casing.

Define a default section for any imports that don't fit into the specified section-order.

Whether to automatically mark imports from within the same package as first-party. For example, when detect-same-package = true, then when analyzing files within the foo package, any imports from within the foo package will be considered first-party.

This heuristic is often unnecessary when src is configured to detect all first-party sources; however, if src is not configured, this heuristic can be useful to detect first-party imports from within (but not across) first-party packages.

A list of modules to consider standard-library, in addition to those known to Ruff in advance.

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

Forces all from imports to appear on their own line.

Don't sort straight-style imports (like import sys) before from-style imports (like from itertools import groupby). Instead, sort the imports by module, independent of import style.

Force specific imports to the top of their appropriate section.

Force import from statements with multiple members and at least one alias (e.g., import A as B) to wrap such that every line contains exactly one member. For example, this formatting would be retained, rather than condensing to a single line:

from .utils import (
    test_directory as test_directory,
    test_id as test_id
)

Note that this setting is only effective when combined with combine-as-imports = true. When combine-as-imports isn't enabled, every aliased import from will be given its own line, in which case, wrapping is not necessary.

When using the formatter, ensure that format.skip-magic-trailing-comma is set to false (default) when enabling force-wrap-aliases to avoid that the formatter collapses members if they all fit on a single line.

A list of modules to separate into auxiliary block(s) of imports, in the order specified.

Whether to place import from imports before straight imports when sorting.

For example, by default, imports will be sorted such that straight imports appear before import from imports, as in:

import os
import sys
from typing import List

Setting from-first = true will instead sort such that import from imports appear before straight imports, as in:

from typing import List
import os
import sys

A mapping from import section names to their heading comments.

When set, a comment with the specified text will be added above imports in the corresponding section. If a heading comment already exists, it will be replaced.

Compatible with isort's import_heading_{section_name} settings.

A list of modules to consider first-party, regardless of whether they can be identified as such via introspection of the local filesystem.

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

A list of modules to consider being a local folder. Generally, this is reserved for relative imports (from . import module).

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

A list of modules to consider third-party, regardless of whether they can be identified as such via introspection of the local filesystem.

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

Sort imports by their string length, such that shorter imports appear before longer imports. For example, by default, imports will be sorted alphabetically, as in:

import collections
import os

Setting length-sort = true will instead sort such that shorter imports appear before longer imports, as in:

import os
import collections

Sort straight imports by their string length. Similar to length-sort, but applies only to straight imports and doesn't affect from imports.

The number of blank lines to place after imports. Use -1 for automatic determination.

Ruff uses at most one blank line after imports in typing stub files (files with .pyi extension) in accordance to the typing style recommendations (source).

When using the formatter, only the values -1, 1, and 2 are compatible because it enforces at least one empty and at most two empty lines after imports.

The number of lines to place between "direct" and import from imports.

When using the formatter, only the values 0 and 1 are compatible because it preserves up to one empty line after imports in nested blocks.

A list of sections that should not be delineated from the previous section via empty lines.

Put all imports into the same section bucket.

For example, rather than separating standard library and third-party imports, as in:

import os
import sys

import numpy
import pandas

Setting no-sections = true will instead group all imports into a single section:

import numpy
import os
import pandas
import sys

Order imports by type, which is determined by case, in addition to alphabetically.

Note that this option takes precedence over the case-sensitive setting when enabled.

Whether to place "closer" imports (fewer . characters, most local) before "further" imports (more . characters, least local), or vice versa.

The default ("furthest-to-closest") is equivalent to isort's reverse-relative default (reverse-relative = false); setting this to "closest-to-furthest" is equivalent to isort's reverse-relative = true.

Add the specified import line to all files.

Override in which order the sections should be output. Can be used to move custom sections.

A list of mappings from section names to modules.

By default, imports are categorized according to their type (e.g., future, third-party, and so on). This setting allows you to group modules into custom sections, to augment or override the built-in sections.

For example, to group all testing utilities, you could create a testing section:

testing = ["pytest", "hypothesis"]

The values in the list are treated as glob patterns. For example, to match all packages in the LangChain ecosystem (langchain-core, langchain-openai, etc.):

langchain = ["langchain-*"]

Custom sections should typically be inserted into the section-order list to ensure that they're displayed as a standalone group and in the intended order, as in:

section-order = [
  "future",
  "standard-library",
  "third-party",
  "first-party",
  "local-folder",
  "testing"
]

If a custom section is omitted from section-order, imports in that section will be assigned to the default-section (which defaults to third-party).

One or more modules to exclude from the single line rule.

If a comma is placed after the last member in a multi-line import, then the imports will never be folded into one line.

See isort's split-on-trailing-comma option.

When using the formatter, ensure that format.skip-magic-trailing-comma is set to false (default) when enabling split-on-trailing-comma to avoid that the formatter removes the trailing commas.

An override list of tokens to always recognize as a var for order-by-type regardless of casing.

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

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_.

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.

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.

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

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

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

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

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

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

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

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.

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

Options for the flake8-annotations plugin.

Options for the flake8-bandit plugin.

Options for the flake8-boolean-trap plugin.

Options for the flake8-bugbear plugin.

Options for the flake8-builtins plugin.

Options for the flake8-comprehensions plugin.

Options for the flake8-copyright plugin.

Options for the flake8-errmsg plugin.

Options for the flake8-gettext plugin.

Options for the flake8-implicit-str-concat plugin.

Options for the flake8-import-conventions plugin.

Options for the flake8-pytest-style plugin.

Options for the flake8-quotes plugin.

Options for the flake8_self plugin.

Options for the flake8-tidy-imports plugin.

Options for the flake8-type-checking plugin.

Options for the flake8-unused-arguments plugin.

Whether to allow rules to add from __future__ import annotations in cases where this would simplify a fix or enable a new diagnostic.

For example, TC001, TC002, and TC003 can move more imports into TYPE_CHECKING blocks if __future__ annotations are enabled.

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.

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.

Options for the isort plugin.

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).

Options for the mccabe plugin.

Options for the pep8-naming plugin.

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.

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

Options for the pycodestyle plugin.

Options for the pydoclint plugin.

Options for the pydocstyle plugin.

Options for the pyflakes plugin.

Options for the pylint plugin.

Options for the pyupgrade plugin.

Options for the ruff plugin

A list of rule codes or prefixes to enable. 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.

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.

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.

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.

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

The maximum McCabe complexity to allow before triggering C901 errors.

A list of decorators that, when applied to a method, indicate that the method should be treated as a class method (in addition to the builtin @classmethod).

For example, Ruff will expect that any method decorated by a decorator in this list takes a cls argument as its first argument.

Expects to receive a list of fully-qualified names (e.g., pydantic.validator, rather than validator) or alternatively a plain name which is then matched against the last segment in case the decorator itself consists of a dotted name.

Additional names (or patterns) to ignore when considering pep8-naming violations, in addition to those included in ignore-names.

Supports glob patterns. For example, to ignore all names starting with test_ or ending with _test, you could use ignore-names = ["test_*", "*_test"]. For more information on the glob syntax, refer to the globset documentation.

A list of names (or patterns) to ignore when considering pep8-naming violations.

Supports glob patterns. For example, to ignore all names starting with test_ or ending with _test, you could use ignore-names = ["test_*", "*_test"]. For more information on the glob syntax, refer to the globset documentation.

A list of decorators that, when applied to a method, indicate that the method should be treated as a static method (in addition to the builtin @staticmethod).

For example, Ruff will expect that any method decorated by a decorator in this list has no self or cls argument.

Expects to receive a list of fully-qualified names (e.g., belay.Device.teardown, rather than teardown) or alternatively a plain name which is then matched against the last segment in case the decorator itself consists of a dotted name.

Whether to avoid PEP 585 (List[int] -> list[int]) and PEP 604 (Union[str, int] -> str | int) rewrites even if a file imports from __future__ import annotations.

This setting is only applicable when the target Python version is below 3.9 and 3.10 respectively, and is most commonly used when working with libraries like Pydantic and FastAPI, which rely on the ability to parse type annotations at runtime. The use of from __future__ import annotations causes Python to treat the type annotations as strings, which typically allows for the use of language features that appear in later Python versions but are not yet supported by the current version (e.g., str | int). However, libraries that rely on runtime type annotations will break if the annotations are incompatible with the current Python version.

For example, while the following is valid Python 3.8 code due to the presence of from __future__ import annotations, the use of str | int prior to Python 3.10 will cause Pydantic to raise a TypeError at runtime:

from __future__ import annotations

import pydantic

class Foo(pydantic.BaseModel):
    bar: str | int

Whether line-length violations (E501) should be triggered for comments starting with task-tags (by default: "TODO", "FIXME", and "XXX").

The maximum line length to allow for doc-line-too-long violations within documentation (W505), including standalone comments. By default, this is set to null which disables reporting violations.

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

See the doc-line-too-long rule for more information.

The maximum line length to allow for line-too-long violations. By default, this is set to the value of the line-length option.

Use this option when you want to detect extra-long lines that the formatter can't automatically split by setting pycodestyle.line-length to a value larger than line-length.

# The formatter wraps lines at a length of 88.
line-length = 88

[pycodestyle]
# E501 reports lines that exceed the length of 100.
max-line-length = 100

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.

See the line-too-long rule for more information.

Skip docstrings which fit on a single line.

Note: The corresponding setting in pydoclint is named skip-checking-short-docstrings.

Whether to use Google-style, NumPy-style conventions, or the PEP 257 defaults when analyzing docstring sections.

Enabling a convention will disable all rules that are not included in the specified convention. As such, the intended workflow is to enable a convention and then selectively enable or disable any additional rules on top of it.

For example, to use Google-style conventions but avoid requiring documentation for every function parameter:

[tool.ruff.lint]
# Enable all `pydocstyle` rules, limiting to those that adhere to the
# Google convention via `convention = "google"`, below.
select = ["D"]

# On top of the Google convention, disable `D417`, which requires
# documentation for every function parameter.
ignore = ["D417"]

[tool.ruff.lint.pydocstyle]
convention = "google"

To enable an additional rule that's excluded from the convention, select the desired rule via its fully qualified rule code (e.g., D400 instead of D4 or D40):

[tool.ruff.lint]
# Enable D400 on top of the Google convention.
extend-select = ["D400"]

[tool.ruff.lint.pydocstyle]
convention = "google"

Ignore docstrings for functions or methods decorated with the specified fully-qualified decorators.

If set to true, ignore missing documentation for *args and **kwargs parameters.

A list of decorators that, when applied to a method, indicate that the method should be treated as a property (in addition to the builtin @property and standard-library @functools.cached_property).

For example, Ruff will expect that any method decorated by a decorator in this list can use a non-imperative summary line.

A list of modules to ignore when considering unused imports.

Used to prevent violations for specific modules that are known to have side effects on import (e.g., hvplot.pandas).

Modules in this list are expected to be fully-qualified names (e.g., hvplot.pandas). Any submodule of a given module will also be ignored (e.g., given hvplot, hvplot.pandas will also be ignored).

Additional functions or classes to consider generic, such that any subscripts should be treated as type annotation (e.g., ForeignKey in django.db.models.ForeignKey["User"].

Expects to receive a list of fully-qualified names (e.g., django.db.models.ForeignKey, rather than ForeignKey).

Dunder methods name to allow, in addition to the default set from the Python standard library (see PLW3201).

Constant types to ignore when used as "magic values" (see PLR2004).

Maximum number of arguments allowed for a function or method definition (see PLR0913).

Maximum number of Boolean expressions allowed within a single if statement (see PLR0916).

Maximum number of branches allowed for a function or method body (see PLR0912).

Maximum number of local variables allowed for a function or method body (see PLR0914).

Maximum number of nested blocks allowed within a function or method body (see PLR1702).

Maximum number of positional arguments allowed for a function or method definition (see PLR0917).

If not specified, defaults to the value of max-args.

Maximum number of public methods allowed for a class (see PLR0904).

Maximum number of return statements allowed for a function or method body (see PLR0911)

Maximum number of statements allowed for a function or method body (see PLR0915).

A list of callable names, whose result may be safely passed into markupsafe.Markup.

Expects to receive a list of fully-qualified names (e.g., bleach.clean, rather than clean).

This setting helps you avoid false positives in code like:

from bleach import clean
from markupsafe import Markup

cleaned_markup = Markup(clean(some_user_input))

Where the use of bleach.clean usually ensures that there's no XSS vulnerability.

Although it is not recommended, you may also use this setting to whitelist other kinds of calls, e.g. calls to i18n translation functions, where how safe that is will depend on the implementation and how well the translations are audited.

Another common use-case is to wrap the output of functions that generate markup like xml.etree.ElementTree.tostring or template rendering engines where sanitization of potential user input is either already baked in or has to happen before rendering.

A list of additional callable names that behave like markupsafe.Markup.

Expects to receive a list of fully-qualified names (e.g., webhelpers.html.literal, rather than literal).

Whether to prefer accessing items keyed by tuples with parentheses around the tuple (see RUF031).

Whether to require __init__.py files to contain no code at all, including imports and docstrings (see RUF067).