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:
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:
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_cachein the tree),foo.py(to exclude any file namedfoo.py), orfoo_*.py(to exclude any file matchingfoo_*.py). - Relative patterns, like
directory/foo.py(to exclude that specific file) ordirectory/*.py(to exclude any Python files indirectory). Note that these paths are relative to the project root (e.g., the directory containing yourpyproject.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:
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:
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_cachein the tree),foo.py(to exclude any file namedfoo.py), orfoo_*.py(to exclude any file matchingfoo_*.py). - Relative patterns, like
directory/foo.py(to exclude that specific file) ordirectory/*.py(to exclude any Python files indirectory). Note that these paths are relative to the project root (e.g., the directory containing yourpyproject.toml).
For more information on the glob syntax, refer to the globset documentation.
Default value: []
Type: list[str]
Example usage:
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:
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:
fix-only
Like fix, but disables reporting on leftover violation. Implies fix.
Default value: false
Type: bool
Example usage:
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:
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:
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:
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:
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:
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"
Type: "full" | "concise" | "grouped" | "json" | "junit" | "github" | "gitlab" | "pylint" | "azure"
Example usage:
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:
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:
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:
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:
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.tomlfile (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:
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:
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":
If both are specified, target-version takes precedence over
requires-python.
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:
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:
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:
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:
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_cachein the tree),foo.py(to exclude any file namedfoo.py), orfoo_*.py(to exclude any file matchingfoo_*.py). - Relative patterns, like
directory/foo.py(to exclude that specific file) ordirectory/*.py(to exclude any Python files indirectory). Note that these paths are relative to the project root (e.g., the directory containing yourpyproject.toml).
For more information on the glob syntax, refer to the globset documentation.
Default value: []
Type: list[str]
Example usage:
include-dependencies
A map from file path to the list of 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:
preview
Whether to enable preview mode. When preview mode is enabled, Ruff will expose unstable commands.
Default value: false
Type: bool
Example usage:
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:
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:
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_cachein the tree),foo.py(to exclude any file namedfoo.py), orfoo_*.py(to exclude any file matchingfoo_*.py). - Relative patterns, like
directory/foo.py(to exclude that specific file) ordirectory/*.py(to exclude any Python files indirectory). Note that these paths are relative to the project root (e.g., the directory containing yourpyproject.toml).
For more information on the glob syntax, refer to the globset documentation.
Default value: []
Type: list[str]
Example usage:
indent-style
Whether to use spaces or tabs for indentation.
indent-style = "space" (default):
indent-style = "tab":
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:
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\nfor 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\non Unix and\r\non Windows.
Default value: "auto"
Type: "auto" | "lf" | "cr-lf" | "native"
Example usage:
preview
Whether to enable the unstable preview style formatting.
Default value: false
Type: bool
Example usage:
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:
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:
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:
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:
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:
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_cachein the tree),foo.py(to exclude any file namedfoo.py), orfoo_*.py(to exclude any file matchingfoo_*.py). - Relative patterns, like
directory/foo.py(to exclude that specific file) ordirectory/*.py(to exclude any Python files indirectory). Note that these paths are relative to the project root (e.g., the directory containing yourpyproject.toml).
For more information on the glob syntax, refer to the globset documentation.
Default value: []
Type: list[str]
Example usage:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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: ["E4", "E7", "E9", "F"]
Type: list[RuleSelector]
Example usage:
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:
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:
unfixable
A list of rule codes or prefixes to consider non-fixable.
Default value: []
Type: list[RuleSelector]
Example usage:
lint.flake8-annotations
allow-star-arg-any
Whether to suppress ANN401 for dynamically typed *args and
**kwargs arguments.
Default value: false
Type: bool
Example usage:
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:
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:
suppress-dummy-args
Whether to suppress ANN000-level violations for arguments matching the
"dummy" variable regex (like _).
Default value: false
Type: bool
Example usage:
suppress-none-returning
Whether to suppress ANN200-level violations for functions that meet
either of the following criteria:
- Contain no
returnstatement. - Explicit
returnstatement(s) all returnNone(explicitly or implicitly).
Default value: false
Type: bool
Example usage:
lint.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:
hardcoded-tmp-directory
A list of directories to consider temporary (see S108).
Default value: ["/tmp", "/var/tmp", "/dev/shm"]
Type: list[str]
Example usage:
hardcoded-tmp-directory-extend
A list of directories to consider temporary, in addition to those
specified by hardcoded-tmp-directory (see S108).
Default value: []
Type: list[str]
Example usage:
lint.flake8-boolean-trap
extend-allowed-calls
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).
Default value: []
Type: list[str]
Example usage:
lint.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:
lint.flake8-builtins
builtins-allowed-modules
List of builtin module names to allow.
Default value: []
Type: list[str]
Example usage:
builtins-ignorelist
Ignore list of builtins.
Default value: []
Type: list[str]
Example usage:
lint.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:
lint.flake8-copyright
author
Author to enforce within the copyright notice. If provided, the author must be present immediately following the copyright notice.
Default value: null
Type: str
Example usage:
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:
notice-rgx
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 2023Copyright (C) 2023Copyright 2021-2023Copyright (C) 2021-2023Copyright (C) 2021, 2023
Default value: "(?i)Copyright\s+((?:\(C\)|©)\s+)?\d{4}((-|,\s)\d{4})*"
Type: str
Example usage:
lint.flake8-errmsg
max-string-length
Maximum string length for string literals in exception messages.
Default value: 0
Type: int
Example usage:
lint.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:
function-names
The function names to consider as internationalization calls.
Default value: ["_", "gettext", "ngettext"]
Type: list[str]
Example usage:
lint.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).
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.
Default value: true
Type: bool
Example usage:
lint.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", "xml.etree.ElementTree": "ET"}
Type: dict[str, str]
Example usage:
banned-aliases
A mapping from module to its banned import aliases.
Default value: {}
Type: dict[str, list[str]]
Example usage:
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:
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:
lint.flake8-pytest-style
fixture-parentheses
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.
Default value: false
Type: bool
Example usage:
mark-parentheses
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.
Default value: false
Type: bool
Example usage:
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:
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:
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:
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:
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:
lint.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:
docstring-quotes
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.
Default value: "double"
Type: "single" | "double"
Example usage:
inline-quotes
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.
Default value: "double"
Type: "single" | "double"
Example usage:
multiline-quotes
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.
Default value: "double"
Type: "single" | "double"
Example usage:
lint.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:
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:
lint.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:
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:
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:
lint.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:
quote-annotations
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:
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.
Default value: false
Type: bool
Example usage:
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:
runtime-evaluated-decorators
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).
Default value: []
Type: list[str]
Example usage:
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:
lint.flake8-unused-arguments
ignore-variadic-names
Whether to allow unused variadic arguments, like *args and **kwargs.
Default value: false
Type: bool
Example usage:
lint.isort
case-sensitive
Sort imports taking into account case sensitivity.
Default value: false
Type: bool
Example usage:
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:
combine-as-imports
Combines as imports on the same line. See isort's combine-as-imports
option.
Default value: false
Type: bool
Example usage:
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:
default-section
Define a default section for any imports that don't fit into the specified section-order.
Default value: "third-party"
Type: str
Example usage:
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:
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:
force-single-line
Forces all from imports to appear on their own line.
Default value: false
Type: bool
Example usage:
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:
force-to-top
Force specific imports to the top of their appropriate section.
Default value: []
Type: list[str]
Example usage:
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:
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.
Default value: false
Type: bool
Example usage:
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:
from-first
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:
Setting from-first = true will instead sort such that import from imports appear
before straight imports, as in:
Default value: false
Type: bool
Example usage:
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:
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:
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:
length-sort
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:
Setting length-sort = true will instead sort such that shorter imports
appear before longer imports, as in:
Default value: false
Type: bool
Example usage:
length-sort-straight
Sort straight imports by their string length. Similar to length-sort,
but applies only to straight imports and doesn't affect from imports.
Default value: false
Type: bool
Example usage:
lines-after-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.
Default value: -1
Type: int
Example usage:
lines-between-types
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.
Default value: 0
Type: int
Example usage:
no-lines-before
A list of sections that should not be delineated from the previous section via empty lines.
Default value: []
Type: list["future" | "standard-library" | "third-party" | "first-party" | "local-folder" | str]
Example usage:
no-sections
Put all imports into the same section bucket.
For example, rather than separating standard library and third-party imports, as in:
Setting no-sections = true will instead group all imports into a single section:
Default value: false
Type: bool
Example usage:
order-by-type
Order imports by type, which is determined by case, in addition to alphabetically.
Default value: true
Type: bool
Example usage:
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:
required-imports
Add the specified import line to all files.
Default value: []
Type: list[str]
Example usage:
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"]
Type: list["future" | "standard-library" | "third-party" | "first-party" | "local-folder" | str]
Example usage:
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:
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.):
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).
Default value: {}
Type: dict[str, list[str]]
Example usage:
single-line-exclusions
One or more modules to exclude from the single line rule.
Default value: []
Type: list[str]
Example usage:
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.
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.
Default value: true
Type: bool
Example usage:
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:
lint.mccabe
max-complexity
The maximum McCabe complexity to allow before triggering C901 errors.
Default value: 10
Type: int
Example usage:
lint.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.
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.
Default value: []
Type: list[str]
Example usage:
[tool.ruff.lint.pep8-naming]
classmethod-decorators = [
# Allow Pydantic's `@validator` decorator to trigger class method treatment.
"pydantic.validator",
# Allow SQLAlchemy's dynamic decorators, like `@field.expression`, to trigger class method treatment.
"declared_attr",
"expression",
"comparator",
]
extend-ignore-names
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.
Default value: []
Type: list[str]
Example usage:
ignore-names
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.
Default value: ["setUp", "tearDown", "setUpClass", "tearDownClass", "setUpModule", "tearDownModule", "asyncSetUp", "asyncTearDown", "setUpTestData", "failureException", "longMessage", "maxDiff"]
Type: list[str]
Example usage:
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.
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.
Default value: []
Type: list[str]
Example usage:
lint.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:
max-doc-length
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.
Default value: null
Type: int
Example usage:
max-line-length
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.
Default value: null
Type: int
Example usage:
lint.pydocstyle
convention
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"
Default value: null
Type: "google" | "numpy" | "pep257"
Example usage:
ignore-decorators
Ignore docstrings for functions or methods decorated with the specified fully-qualified decorators.
Default value: []
Type: list[str]
Example usage:
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:
lint.pyflakes
allowed-unused-imports
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).
Default value: []
Type: list[str]
Example usage:
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:
lint.pylint
allow-dunder-method-names
Dunder methods name to allow, in addition to the default set from the
Python standard library (see PLW3201).
Default value: []
Type: list[str]
Example usage:
allow-magic-value-types
Constant types to ignore when used as "magic values" (see PLR2004).
Default value: ["str", "bytes"]
Type: list["str" | "bytes" | "complex" | "float" | "int"]
Example usage:
max-args
Maximum number of arguments allowed for a function or method definition
(see PLR0913).
Default value: 5
Type: int
Example usage:
max-bool-expr
Maximum number of Boolean expressions allowed within a single if statement
(see PLR0916).
Default value: 5
Type: int
Example usage:
max-branches
Maximum number of branches allowed for a function or method body (see PLR0912).
Default value: 12
Type: int
Example usage:
max-locals
Maximum number of local variables allowed for a function or method body (see PLR0914).
Default value: 15
Type: int
Example usage:
max-nested-blocks
Maximum number of nested blocks allowed within a function or method body
(see PLR1702).
Default value: 5
Type: int
Example usage:
max-positional-args
Maximum number of positional arguments allowed for a function or method definition
(see PLR0917).
If not specified, defaults to the value of max-args.
Default value: 5
Type: int
Example usage:
max-public-methods
Maximum number of public methods allowed for a class (see PLR0904).
Default value: 20
Type: int
Example usage:
max-returns
Maximum number of return statements allowed for a function or method
body (see PLR0911)
Default value: 6
Type: int
Example usage:
max-statements
Maximum number of statements allowed for a function or method body (see PLR0915).
Default value: 50
Type: int
Example usage:
lint.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:
Default value: false
Type: bool
Example usage:
lint.ruff
extend-markup-names
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).
Default value: []
Type: list[str]
Example usage:
parenthesize-tuple-in-subscript
Whether to prefer accessing items keyed by tuples with
parentheses around the tuple (see RUF031).
Default value: false
Type: bool
Example usage: