Settings#

Top-level#

`allowed-confusables`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff]
# 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 = ["−", "ρ", "∗"]

`builtins`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff]
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:

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

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: re.Pattern

Example usage:

[tool.ruff]
# Only ignore variables named "_".
dummy-variable-rgx = "^_$"

`exclude`#

A list of file patterns to exclude from 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", "build", "dist", "node_modules", "venv"]

Type: list[str]

Example usage:

[tool.ruff]
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: None

Type: str

Example usage:

[tool.ruff]
# 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 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:

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

`extend-fixable`#

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

Default value: []

Type: list[RuleSelector]

Example usage:

[tool.ruff]
# Enable autofix for flake8-bugbear (`B`), on top of any rules specified by `fixable`.
extend-fixable = ["B"]

`extend-ignore`#

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

This option has been deprecated in favor of ignore since its usage is now interchangeable with ignore.

Default value: []

Type: list[RuleSelector]

Example usage:

[tool.ruff]
# Skip unused variable rules (`F841`).
extend-ignore = ["F841"]

`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:

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

`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:

[tool.ruff]
# Also ignore `E402` in all `__init__.py` files.
[tool.ruff.extend-per-file-ignores]
"__init__.py" = ["E402"]

`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:

[tool.ruff]
# On top of the default `select` (`E`, `F`), enable flake8-bugbear (`B`) and flake8-quotes (`Q`).
extend-select = ["B", "Q"]

`external`#

A list of rule codes 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:

[tool.ruff]
# Avoiding flagging (and removing) `V101` from any `# noqa`
# directives, despite Ruff's lack of support for `vulture`.
external = ["V101"]

`fix`#

Enable autofix behavior by-default when running ruff (overridden by the --fix and --no-fix command-line flags).

Default value: false

Type: bool

Example usage:

[tool.ruff]
fix = true

`fix-only`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff]
fix-only = true

`fixable`#

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

Default value: ["ALL"]

Type: list[RuleSelector]

Example usage:

[tool.ruff]
# Only allow autofix behavior for `E` and `F` rules.
fixable = ["E", "F"]

`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:

[tool.ruff]
force-exclude = true

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

Default value: []

Type: list[RuleSelector]

Example usage:

[tool.ruff]
# Skip unused variable rules (`F841`).
ignore = ["F841"]

`ignore-init-module-imports`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff]
ignore-init-module-imports = 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.

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

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

Type: list[str]

Example usage:

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

`line-length`#

The line length to use when enforcing long-lines violations (like E501). Must be greater than 0 and less than or equal to 320.

Default value: 88

Type: int

Example usage:

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

`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:

[tool.ruff]
logger-objects = ["logging_setup.logger"]

`namespace-packages`#

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

Default value: []

Type: list[str]

Example usage:

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

`output-format`#

The style in which violation messages should be formatted: "text" (default), "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: "text"

Example usage:

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

`per-file-ignores`#

A list of mappings from file pattern to rule codes or prefixes to exclude, when considering any matching files.

Default value: {}

Type: dict[str, list[RuleSelector]]

Example usage:

[tool.ruff]
# Ignore `E402` (import violations) in all `__init__.py` files, and in `path/to/file.py`.
[tool.ruff.per-file-ignores]
"__init__.py" = ["E402"]
"path/to/file.py" = ["E402"]

`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:

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

`required-version`#

Require a specific version of Ruff to be running (useful for unifying results across many environments, e.g., with a pyproject.toml file).

Default value: None

Type: str

Example usage:

[tool.ruff]
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:

[tool.ruff]
respect-gitignore = false

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

When breaking ties between enabled and disabled rules (via select and ignore, respectively), more specific prefixes override less specific prefixes.

Default value: ["E", "F"]

Type: list[RuleSelector]

Example usage:

[tool.ruff]
# On top of the defaults (`E`, `F`), enable flake8-bugbear (`B`) and flake8-quotes (`Q`).
select = ["E", "F", "B", "Q"]

`show-fixes`#

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

Default value: false

Type: bool

Example usage:

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

`show-source`#

Whether to show source code snippets when reporting lint violations (overridden by the --show-source command-line flag).

Default value: false

Type: bool

Example usage:

[tool.ruff]
# By default, always show source code snippets.
show-source = true

`src`#

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

As an example: given a Python package structure like:

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

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

When omitted, the src directory will typically default to the directory containing the nearest pyproject.toml, ruff.toml, or .ruff.toml file (the "project root"), unless a configuration file is explicitly provided (e.g., via the --config command-line flag).

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 of the packages in that directory. User home directory and environment variables will also be expanded.

Default value: ["."]

Type: list[str]

Example usage:

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

`tab-size`#

The tabulation size to calculate line length.

Default value: 4

Type: int

Example usage:

[tool.ruff]
tab-size = 8

`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 omitted, and Ruff is configured via a pyproject.toml file, the target version will be inferred from its project.requires-python field (e.g., requires-python = ">=3.8"). If Ruff is configured via ruff.toml or .ruff.toml, no such inference will be performed.

Default value: "py38"

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

Example usage:

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

`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:

[tool.ruff]
task-tags = ["HACK"]

`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:

[tool.ruff]
typing-modules = ["airflow.typing_compat"]

`unfixable`#

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

Default value: []

Type: list[RuleSelector]

Example usage:

[tool.ruff]
# Disable autofix for unused imports (`F401`).
unfixable = ["F401"]

flake8-annotations#

`allow-star-arg-any`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-annotations]
allow-star-arg-any = true

`ignore-fully-untyped`#

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.

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-annotations]
ignore-fully-untyped = true

`mypy-init-return`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-annotations]
mypy-init-return = true

`suppress-dummy-args`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-annotations]
suppress-dummy-args = true

`suppress-none-returning`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-annotations]
suppress-none-returning = true

flake8-bandit#

`check-typed-exception`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-bandit]
check-typed-exception = true

`hardcoded-tmp-directory`#

A list of directories to consider temporary.

Default value: ["/tmp", "/var/tmp", "/dev/shm"]

Type: list[str]

Example usage:

[tool.ruff.flake8-bandit]
hardcoded-tmp-directory = ["/foo/bar"]

`hardcoded-tmp-directory-extend`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-bandit]
extend-hardcoded-tmp-directory = ["/foo/bar"]

flake8-bugbear#

`extend-immutable-calls`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-bugbear]
# Allow default arguments like, e.g., `data: List[str] = fastapi.Query(None)`.
extend-immutable-calls = ["fastapi.Depends", "fastapi.Query"]

flake8-builtins#

`builtins-ignorelist`#

Ignore list of builtins.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-builtins]
builtins-ignorelist = ["id"]

flake8-comprehensions#

`allow-dict-calls-with-keyword-arguments`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-comprehensions]
allow-dict-calls-with-keyword-arguments = true

flake8-copyright#

`author`#

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

Default value: None

Type: str

Example usage:

[tool.ruff.flake8-copyright]
author = "Ruff"

`min-file-size`#

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

Default value: 0

Type: int

Example usage:

[tool.ruff.flake8-copyright]
# Avoid enforcing a header on files smaller than 1024 bytes.
min-file-size = 1024

`notice-rgx`#

The regular expression used to match the copyright notice, compiled with the regex crate.

Default value: (?i)Copyright\s+($C$\s+)?\d{4}([-,]\d{4})*

Type: str

Example usage:

[tool.ruff.flake8-copyright]
notice-rgx = "(?i)Copyright \\(C\\) \\d{4}"

flake8-errmsg#

`max-string-length`#

Maximum string length for string literals in exception messages.

Default value: 0

Type: int

Example usage:

[tool.ruff.flake8-errmsg]
max-string-length = 20

flake8-gettext#

`extend-function-names`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-gettext]
extend-function-names = ["ugettetxt"]

`function-names`#

The function names to consider as internationalization calls.

Default value: ["_", "gettext", "ngettext"]

Type: list[str]

Example usage:

[tool.ruff.flake8-gettext]
function-names = ["_", "gettext", "ngettext", "ugettetxt"]

flake8-implicit-str-concat#

`allow-multiline`#

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

Note that setting allow-multiline = false should typically be coupled with disabling explicit-string-concatenation (ISC003). Otherwise, both explicit and implicit multiline string concatenations will be seen as violations.

Default value: true

Type: bool

Example usage:

[tool.ruff.flake8-implicit-str-concat]
allow-multiline = false

flake8-import-conventions#

`aliases`#

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

Default value: {"altair": "alt", "matplotlib": "mpl", "matplotlib.pyplot": "plt", "numpy": "np", "pandas": "pd", "seaborn": "sns", "tensorflow": "tf", "tkinter": "tk", "holoviews": "hv", "panel": "pn", "plotly.express": "px", "polars": "pl", "pyarrow": "pa"}

Type: dict[str, str]

Example usage:

[tool.ruff.flake8-import-conventions]
[tool.ruff.flake8-import-conventions.aliases]
# Declare the default aliases.
altair = "alt"
"matplotlib.pyplot" = "plt"
numpy = "np"
pandas = "pd"
seaborn = "sns"
scipy = "sp"

`banned-aliases`#

A mapping from module to its banned import aliases.

Default value: {}

Type: dict[str, list[str]]

Example usage:

[tool.ruff.flake8-import-conventions]
[tool.ruff.flake8-import-conventions.banned-aliases]
# Declare the banned aliases.
"tensorflow.keras.backend" = ["K"]

`banned-from`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-import-conventions]
# Declare the banned `from` imports.
banned-from = ["typing"]

`extend-aliases`#

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

Default value: {}

Type: dict[str, str]

Example usage:

[tool.ruff.flake8-import-conventions]
[tool.ruff.flake8-import-conventions.extend-aliases]
# Declare a custom alias for the `matplotlib` module.
"dask.dataframe" = "dd"

flake8-pytest-style#

`fixture-parentheses`#

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

Default value: true

Type: bool

Example usage:

[tool.ruff.flake8-pytest-style]
fixture-parentheses = true

`mark-parentheses`#

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

Default value: true

Type: bool

Example usage:

[tool.ruff.flake8-pytest-style]
mark-parentheses = true

`parametrize-names-type`#

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'], ...)

Default value: tuple

Type: "csv" | "tuple" | "list"

Example usage:

[tool.ruff.flake8-pytest-style]
parametrize-names-type = "list"

`parametrize-values-row-type`#

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

Default value: tuple

Type: "tuple" | "list"

Example usage:

[tool.ruff.flake8-pytest-style]
parametrize-values-row-type = "list"

`parametrize-values-type`#

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

Default value: list

Type: "tuple" | "list"

Example usage:

[tool.ruff.flake8-pytest-style]
parametrize-values-type = "tuple"

`raises-extend-require-match-for`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-pytest-style]
raises-extend-require-match-for = ["requests.RequestException"]

`raises-require-match-for`#

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.

Default value: ["BaseException", "Exception", "ValueError", "OSError", "IOError", "EnvironmentError", "socket.error"]

Type: list[str]

Example usage:

[tool.ruff.flake8-pytest-style]
raises-require-match-for = ["requests.RequestException"]

flake8-quotes#

`avoid-escape`#

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.

Default value: true

Type: bool

Example usage:

[tool.ruff.flake8-quotes]
# Don't bother trying to avoid escapes.
avoid-escape = false

`docstring-quotes`#

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

Default value: "double"

Type: "single" | "double"

Example usage:

[tool.ruff.flake8-quotes]
docstring-quotes = "single"

`inline-quotes`#

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

Default value: "double"

Type: "single" | "double"

Example usage:

[tool.ruff.flake8-quotes]
inline-quotes = "single"

`multiline-quotes`#

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

Default value: "double"

Type: "single" | "double"

Example usage:

[tool.ruff.flake8-quotes]
multiline-quotes = "single"

flake8-self#

`extend-ignore-names`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-self]
extend-ignore-names = ["_base_manager", "_default_manager",  "_meta"]

`ignore-names`#

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

Default value: ["_make", "_asdict", "_replace", "_fields", "_field_defaults", "_name_", "_value_"]

Type: list[str]

Example usage:

[tool.ruff.flake8-self]
ignore-names = ["_new"]

flake8-tidy-imports#

`ban-relative-imports`#

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

Default value: "parents"

Type: "parents" | "all"

Example usage:

[tool.ruff.flake8-tidy-imports]
# Disallow all relative imports.
ban-relative-imports = "all"

`banned-api`#

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.

Default value: {}

Type: dict[str, { "msg": str }]

Example usage:

[tool.ruff.flake8-tidy-imports]
[tool.ruff.flake8-tidy-imports.banned-api]
"cgi".msg = "The cgi module is deprecated, see https://peps.python.org/pep-0594/#cgi."
"typing.TypedDict".msg = "Use typing_extensions.TypedDict instead."

`banned-module-level-imports`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-tidy-imports]
# Ban certain modules from being imported at module level, instead requiring
# that they're imported lazily (e.g., within a function definition).
banned-module-level-imports = ["torch", "tensorflow"]

flake8-type-checking#

`exempt-modules`#

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

Default value: ["typing"]

Type: list[str]

Example usage:

[tool.ruff.flake8-type-checking]
exempt-modules = ["typing", "typing_extensions"]

`runtime-evaluated-base-classes`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-type-checking]
runtime-evaluated-base-classes = ["pydantic.BaseModel", "sqlalchemy.orm.DeclarativeBase"]

`runtime-evaluated-decorators`#

Exempt classes decorated with any of the enumerated decorators from needing to be moved into type-checking blocks.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.flake8-type-checking]
runtime-evaluated-decorators = ["attrs.define", "attrs.frozen"]

`strict`#

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

See flake8-type-checking's strict option.

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-type-checking]
strict = true

flake8-unused-arguments#

`ignore-variadic-names`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.flake8-unused-arguments]
ignore-variadic-names = true

format#

Experimental: Configures how ruff format formats your code.

Please provide feedback in this discussion.

`indent-style`#

Whether to use 4 spaces or hard tabs for indenting code.

Defaults to 4 spaces. We care about accessibility; if you do not need tabs for accessibility, we do not recommend you use them.

Default value: space

Type: "space" | "tab"

Example usage:

[tool.ruff.format]
# Use tabs instead of 4 space indentation
indent-style = "tab"

`line-ending`#

The character Ruff uses at the end of a line.

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.
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.
native: Line endings will be converted to \n on Unix and \r\n on Windows.

Default value: lf

Type: "lf" | "crlf" | "auto" | "native"

Example usage:

[tool.ruff.format]
# Automatically detect the line ending on a file per file basis.
line-ending = "auto"

`preview`#

Whether to enable the unstable preview style formatting.

Default value: false

Type: bool

Example usage:

[tool.ruff.format]
# Enable preview style formatting
preview = true

`quote-style`#

Whether to prefer single ' or double " quotes for strings and docstrings.

Ruff may deviate from this option if using the configured quotes would require more escaped quotes:

a = "It's monday morning"
b = "a string without any quotes"

Ruff leaves a unchanged when using quote-style = "single" because it is otherwise necessary to escape the ' which leads to less readable code: 'It\'s monday morning'. Ruff changes the quotes of b to use single quotes.

Default value: double

Type: "double" | "single"

Example usage:

[tool.ruff.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 width 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:

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

isort#

`case-sensitive`#

Sort imports taking into account case sensitivity.

Default value: false

Type: bool

Example usage:

[tool.ruff.isort]
case-sensitive = true

`classes`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
classes = ["SVC"]

`combine-as-imports`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.isort]
combine-as-imports = true

`constants`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
constants = ["constant"]

`detect-same-package`#

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.

Default value: true

Type: bool

Example usage:

[tool.ruff.isort]
detect-same-package = false

`extra-standard-library`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
extra-standard-library = ["path"]

`force-single-line`#

Forces all from imports to appear on their own line.

Default value: false

Type: bool

Example usage:

[tool.ruff.isort]
force-single-line = true

`force-sort-within-sections`#

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.

Default value: false

Type: bool

Example usage:

[tool.ruff.isort]
force-sort-within-sections = true

`force-to-top`#

Force specific imports to the top of their appropriate section.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
force-to-top = ["src"]

`force-wrap-aliases`#

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.

Default value: false

Type: bool

Example usage:

[tool.ruff.isort]
force-wrap-aliases = true
combine-as-imports = true

`forced-separate`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
forced-separate = ["tests"]

`known-first-party`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
known-first-party = ["src"]

`known-local-folder`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
known-local-folder = ["src"]

`known-third-party`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
known-third-party = ["src"]

`lines-after-imports`#

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

Default value: -1

Type: int

Example usage:

[tool.ruff.isort]
# Use a single line after each import block.
lines-after-imports = 1

`lines-between-types`#

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

Default value: 0

Type: int

Example usage:

[tool.ruff.isort]
# Use a single line between direct and from import
lines-between-types = 1

`no-lines-before`#

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

Default value: []

Example usage:

[tool.ruff.isort]
no-lines-before = ["future", "standard-library"]

`order-by-type`#

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

Default value: true

Type: bool

Example usage:

[tool.ruff.isort]
order-by-type = true

`relative-imports-order`#

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.

Default value: furthest-to-closest

Type: "furthest-to-closest" | "closest-to-furthest"

Example usage:

[tool.ruff.isort]
relative-imports-order = "closest-to-furthest"

`required-imports`#

Add the specified import line to all files.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
required-imports = ["from __future__ import annotations"]

`section-order`#

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

Default value: ["future", "standard-library", "third-party", "first-party", "local-folder"]

Example usage:

[tool.ruff.isort]
section-order = ["future", "standard-library", "first-party", "local-folder", "third-party"]

`sections`#

A list of mappings from section names to modules. By default custom sections are output last, but this can be overridden with section-order.

Default value: {}

Type: dict[str, list[str]]

Example usage:

[tool.ruff.isort]
# Group all Django imports into a separate section.
[tool.ruff.isort.sections]
"django" = ["django"]

`single-line-exclusions`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
single-line-exclusions = ["os", "json"]

`split-on-trailing-comma`#

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.

Default value: true

Type: bool

Example usage:

[tool.ruff.isort]
split-on-trailing-comma = false

`variables`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.isort]
variables = ["VAR"]

mccabe#

`max-complexity`#

The maximum McCabe complexity to allow before triggering C901 errors.

Default value: 10

Type: int

Example usage:

[tool.ruff.mccabe]
# Flag errors (`C901`) whenever the complexity level exceeds 5.
max-complexity = 5

pep8-naming#

`classmethod-decorators`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.pep8-naming]
# Allow Pydantic's `@validator` decorator to trigger class method treatment.
classmethod-decorators = ["pydantic.validator"]

`extend-ignore-names`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.pep8-naming]
extend-ignore-names = ["callMethod"]

`ignore-names`#

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

Default value: ["setUp", "tearDown", "setUpClass", "tearDownClass", "setUpModule", "tearDownModule", "asyncSetUp", "asyncTearDown", "setUpTestData", "failureException", "longMessage", "maxDiff"]

Type: list[str]

Example usage:

[tool.ruff.pep8-naming]
ignore-names = ["callMethod"]

`staticmethod-decorators`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.pep8-naming]
# Allow a shorthand alias, `@stcmthd`, to trigger static method treatment.
staticmethod-decorators = ["stcmthd"]

pycodestyle#

`ignore-overlong-task-comments`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.pycodestyle]
ignore-overlong-task-comments = true

`max-doc-length`#

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

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

Default value: None

Type: int

Example usage:

[tool.ruff.pycodestyle]
max-doc-length = 88

pydocstyle#

`convention`#

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

Enabling a convention will force-disable any rules that are not included in the specified convention. As such, the intended use is to enable a convention and then selectively 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]
# 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.pydocstyle]
convention = "google"

As conventions force-disable all rules not included in the convention, enabling additional rules on top of a convention is currently unsupported.

Default value: None

Type: "google" | "numpy" | "pep257"

Example usage:

[tool.ruff.pydocstyle]
# Use Google-style docstrings.
convention = "google"

`ignore-decorators`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.pydocstyle]
ignore-decorators = ["typing.overload"]

`property-decorators`#

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.

Default value: []

Type: list[str]

Example usage:

[tool.ruff.pydocstyle]
property-decorators = ["gi.repository.GObject.Property"]

pyflakes#

`extend-generics`#

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

Default value: []

Type: list[str]

Example usage:

[tool.ruff.pyflakes]
extend-generics = ["django.db.models.ForeignKey"]

pylint#

`allow-magic-value-types`#

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

Default value: ["str", "bytes"]

Example usage:

[tool.ruff.pylint]
allow-magic-value-types = ["int"]

`max-args`#

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

Default value: 5

Type: int

Example usage:

[tool.ruff.pylint]
max-args = 5

`max-branches`#

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

Default value: 12

Type: int

Example usage:

[tool.ruff.pylint]
max-branches = 12

`max-public-methods`#

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

Default value: 20

Type: int

Example usage:

[tool.ruff.pylint]
max-public-methods = 20

`max-returns`#

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

Default value: 6

Type: int

Example usage:

[tool.ruff.pylint]
max-returns = 6

`max-statements`#

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

Default value: 50

Type: int

Example usage:

[tool.ruff.pylint]
max-statements = 50

pyupgrade#

`keep-runtime-typing`#

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

Default value: false

Type: bool

Example usage:

[tool.ruff.pyupgrade]
# Preserve types, even if a file imports `from __future__ import annotations`.
keep-runtime-typing = true