Settings
Top-level
builtins
A list of builtins to treat as defined references, in addition to thesystem 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 inthe current project root.
However, Ruff will also respect theRUFF_CACHE_DIR environmentvariable, which takes precedence over that default.
This setting will override even theRUFF_CACHE_DIR environmentvariable, 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 theglobset documentation.
Note that you'll typically want to useextend-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 localpyproject.toml file to merge into thisconfiguration. User home directory and environment variables will beexpanded.
To resolve the currentpyproject.toml file, Ruff will first resolvethis base configuration file, then merge in any properties definedin 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 thosespecified byexclude.
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 theglobset documentation.
Default value:[]
Type:list[str]
Example usage:
extend-include
A list of file patterns to include when linting, in addition to thosespecified byinclude.
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 theglobset documentation.
Default value:[]
Type:list[str]
Example usage:
fix
Enable fix behavior by-default when runningruff (overriddenby 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
Likefix, but disables reporting on leftover violation. Impliesfix.
Default value:false
Type:bool
Example usage:
force-exclude
Whether to enforceexclude andextend-exclude patterns,even for paths that are passed to Ruff explicitly. Typically, Ruff will lintany paths passed in directly, even if they would typically beexcluded. Settingforce-exclude = true will cause Ruff torespect these exclusions unequivocally.
This is useful forpre-commit, which explicitly passes allchanged files to theruff-pre-commitplugin, regardless of whether they're marked as excluded by Ruff's ownsettings.
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 isincluded 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 theglobset 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 (likeE501) to determine the visualwidth of a tab.
This option changes the number of spaces the formatter inserts whenusing soft-tabs (indent-style = space).
PEP 8 recommends using 4 spaces perindentation level.
Default value:4
Type:int
Example usage:
line-length
The line length to use when enforcing long-lines violations (likeE501)and at whichisort 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, theunicode width of each character is added up to determine the length.
The value must be greater than0 and less than or equal to320.
Note: While the formatter will attempt to format lines such that they remainwithin theline-length, it isn't a hard upper bound, and formatted lines mayexceed theline-length.
Seepycodestyle.max-line-length to configure different lengths forE501 and the formatter.
Default value:88
Type:int
Example usage:
namespace-packages
Mark the specified directories as namespace packages. For the purpose ofmodule resolution, Ruff will treat those directories and all their subdirectoriesas 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" (GitHubActions 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:
per-file-target-version
A list of mappings from glob-style file pattern to Python version to use when checking thecorresponding file(s).
This may be useful for overriding the global Python version settings intarget-version orrequires-python for a subset of files. For example, if you have a project with a minimumsupported Python version of 3.9 but a subdirectory of developer scripts that want to use anewer feature like thematch statement from Python 3.10, you can useper-file-target-version to specify"developer_scripts/*.py" = "py310".
This setting is used by the linter to enforce any enabled version-specific lint rules, aswell as by the formatter for any version-specific formatting options, such as parenthesizingcontext managers on Python 3.10+.
Default value:{}
Type:dict[str, PythonVersion]
Example usage:
preview
Whether to enable preview mode. When preview mode is enabled, Ruff willuse 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 exitwith an error.
Useful for unifying results across many environments, e.g., with apyproject.toml file.
Accepts aPEP 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 globalgitignore 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-partyimports.
When omitted, thesrc 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 andsrc layouts out-of-the-box.(If a configuration file is explicitly provided (e.g., via the--config command-lineflag), 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 thesrc option(e.g.,src = ["lib"]), such that when resolving imports,my_package.foois considered first-party.
This field supports globs. For example, if you have a series of Pythonpackages in apython_modules directory,src = ["python_modules/*"]would expand to incorporate all packages in that directory. User homedirectory 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 automaticcode upgrades, like rewriting type annotations. Ruff will not proposechanges using features that are not available in the given version.
For example, to represent supporting Python >=3.10 or ==3.10specifytarget-version = "py310".
If you're already using apyproject.toml file, we recommendproject.requires-python instead, as it's based on Python packagingstandards, and will be respected by other tools. For example, Rufftreats the following as identical totarget-version = "py38":
If both are specified,target-version takes precedence overrequires-python. SeeInferring the Python versionfor a complete description of how thetarget-version is determinedwhen left unspecified.
Note that a stub file cansometimes make use of a typing featurebefore it is available at runtime, as long as the stub does not makeuse of newsyntax. For example, a type checker will understandint | str in a stub as being aUnion type annotation, even if thetype checker is run using Python 3.9, despite the fact that the|operator can only be used to create union types at runtime on Python3.10+. As such, Ruff will often recommend newer features in a stubfile than it would for an equivalent runtime file with the same targetversion.
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'sanalyze command.
detect-string-imports
Whether to detect imports from string literals. When enabled, Ruff will search for stringliterals that "look like" import paths, and include them in the import map, if they resolveto 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 thatdepend 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 (seeexclude, andextend-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 theglobset documentation.
Default value:[]
Type:list[str]
Example usage:
include-dependencies
A map from file path to the list of Python or non-Python file paths or globs that should beconsidered 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 unstablecommands.
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 areautomatically reformatted.
For example, when this is enabled, the following code:
deff(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 totheir defaults) as:
deff(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) """passIf a code snippet in a docstring contains invalid Python code or if theformatter would otherwise write invalid Python code, then the codeexample is ignored by the formatter and kept as-is.
Currently, doctest, Markdown, reStructuredText literal blocks, andreStructuredText code blocks are all supported and automaticallyrecognized. In the case of unlabeled fenced code blocks in Markdown andreStructuredText literal blocks, the contents are assumed to be Pythonand reformatted. As with any other format, if the contents aren't validPython, 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 thedocstring-code-format setting isenabled.
The default value for this setting is"dynamic", which has the effectof ensuring that any reformatted code examples in docstrings adhere tothe global line length configuration that is used for the surroundingPython code. The point of this setting is that it takes the indentationof the docstring into account when reformatting code examples.
Alternatively, this can be set to a fixed integer, which will resultin the same line length limit being applied to all reformatted codeexamples in docstrings. When set to a fixed integer, the indent of thedocstring is not taken into account. That is, this may result in linesin the reformatted code example that exceed the globally configuredline length limit.
For example, when this is set to20 anddocstring-code-formatis enabled, then this code:
deff(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 setto their defaults) as:
deff(x):""" Something about `f`. And an example: .. code-block:: python ( foo, bar, quux, ) = this_is_a_long_line( lion, hippo, lemur, bear, ) """passDefault value:"dynamic"
Type:int | "dynamic"
Example usage:
exclude
A list of file patterns to exclude from formatting in addition to the files excluded globally (seeexclude, andextend-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 theglobset 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 forindentation.We care about accessibility; if you do not need tabs for accessibility, we do not recommend you use them.
Seeindent-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 withPEP 8 andPEP 257,Ruff prefers double quotes for triple quoted strings and docstrings even when usingquote-style = "single".
Ruff deviates from using the configured quotes if doing so prevents the need forescaping quote characters inside the string:
Ruff will change the quotes of the string assigned toa to single quotes when usingquote-style = "single".However, Ruff uses double quotes for the string assigned tob 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 stylepreserve for projects that already usea mixture of single and double quotes and can't migrate to thedouble orsingle style.The quote stylepreserve 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 totrue, the magic trailing comma is ignored.
For example, Ruff leaves the arguments separate even thoughcollapsing the arguments to a single line doesn't exceed the line length ifskip-magic-trailing-comma = false:
Settingskip-magic-trailing-comma = true changes the formatting to:
# The arguments are collapsed to a single line because the trailing comma is ignoreddeftest(a,b):passDefault value:false
Type:bool
Example usage:
lint
Configures how Ruff checks your code.
Options specified in thelint section take precedence over the deprecated top-level settings.
allowed-confusables
A list of allowed "confusable" Unicode characters to ignore whenenforcingRUF001,RUF002, andRUF003.
Default value:[]
Type:list[str]
Example usage:
dummy-variable-rgx
A regular expression used to identify "dummy" variables, or those whichshould be ignored when enforcing (e.g.) unused-variable rules. Thedefault 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 (seeexclude, andextend-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 theglobset 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 eachpreview 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 thosespecified byfixable.
Default value:[]
Type:list[RuleSelector]
Example usage:
extend-ignore
Deprecated
This option has been deprecated. Theextend-ignore option is now interchangeable withignore. Please update your configuration to use theignore option instead.
A list of rule codes or prefixes to ignore, in addition to thosespecified byignore.
Default value:[]
Type:list[RuleSelector]
Example usage:
extend-per-file-ignores
A list of mappings from file pattern to rule codes or prefixes toexclude, in addition to any rules excluded byper-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 consideredsafe.
Default value:[]
Type:list[RuleSelector]
Example usage:
extend-select
A list of rule codes or prefixes to enable, in addition to thosespecified byselect.
Default value:[]
Type:list[RuleSelector]
Example usage:
extend-unsafe-fixes
A list of rule codes or prefixes for which safe fixes should be consideredunsafe.
Default value:[]
Type:list[RuleSelector]
Example usage:
external
A list of rule codes or prefixes that are unsupported by Ruff, but should bepreserved when (e.g.) validating# noqa directives. Useful forretaining# noqa directives that cover plugins not yet implementedby 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:
future-annotations
Whether to allow rules to addfrom __future__ import annotations in cases where this wouldsimplify a fix or enable a new diagnostic.
For example,TC001,TC002, andTC003 can move more imports intoTYPE_CHECKING blocksif__future__ annotations are enabled.
This setting is currently inpreview and requirespreview mode to be enabled to have any effect.
Default value:false
Type:bool
Example usage:
ignore
A list of rule codes or prefixes to ignore. Prefixes can specify exactrules (likeF841), entire categories (likeF), or anything inbetween.
When breaking ties between enabled and disabled rules (viaselect andignore, respectively), more specific prefixes override lessspecific prefixes.ignore takes precedence overselect if the sameprefix appears in both.
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. Suchimports will still be flagged, but with a dedicated message suggestingthat the import is either added to the module's__all__ symbol, orre-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 importsvia an unsafe fix.
Default value:true
Type:bool
Example usage:
logger-objects
A list of objects that should be treated equivalently to alogging.Logger object.
This is useful for ensuring proper diagnostics (e.g., to identifylogging deprecations and other best-practices) for projects thatre-export alogging.Logger object from a common module.
For example, if you have a modulelogging_setup.py with the followingcontents:
Adding"logging_setup.logger" tologger-objects will ensure thatlogging_setup.logger is treated as alogging.Logger object whenimported 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 toexclude, when considering any matching files. An initial '!' negatesthe file pattern.
Default value:{}
Type:dict[str, list[RuleSelector]]
Example usage:
preview
Whether to enable preview mode. When preview mode is enabled, Ruff willuse unstable rules and fixes.
Default value:false
Type:bool
Example usage:
select
A list of rule codes or prefixes to enable. Prefixes can specify exactrules (likeF841), entire categories (likeF), or anything inbetween.
When breaking ties between enabled and disabled rules (viaselect andignore, respectively), more specific prefixes override lessspecific prefixes.ignore takes precedence overselect if thesame prefix appears in both.
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 codedetection (ERA), and skipped by line-length rules (E501) ifignore-overlong-task-comments is set totrue.
Default value:["TODO", "FIXME", "XXX"]
Type:list[str]
Example usage:
typing-extensions
Whether to allow imports from the third-partytyping_extensions module for Python versionsbefore a symbol was added to the first-partytyping module.
Many rules try to import symbols from thetyping module but fall back totyping_extensions for earlier versions of Python. This option can be used to disable thisfallback behavior in cases wheretyping_extensions is not installed.
Default value:true
Type:bool
Example usage:
typing-modules
A list of modules whose exports should be treated equivalently tomembers of thetyping module.
This is useful for ensuring proper type annotation inference forprojects that re-exporttyping andtyping_extensions membersfrom a compatibility module. If omitted, any members imported frommodules apart fromtyping andtyping_extensions will be treatedas 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
Options for theflake8-annotations plugin.
allow-star-arg-any
Whether to suppressANN401 for dynamically typed*args and**kwargs arguments.
Default value:false
Type:bool
Example usage:
ignore-fully-untyped
Whether to suppressANN* rules for any declarationthat 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 atleast one argument is annotated.
Default value:false
Type:bool
Example usage:
suppress-dummy-args
Whether to suppressANN000-level violations for arguments matching the"dummy" variable regex (like_).
Default value:false
Type:bool
Example usage:
suppress-none-returning
Whether to suppressANN200-level violations for functions that meeteither 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
Options for theflake8-bandit plugin.
allowed-markup-calls
A list of callable names, whose result may be safely passed intomarkupsafe.Markup.
Expects to receive a list of fully-qualified names (e.g.,bleach.clean, rather thanclean).
This setting helps you avoid false positives in code like:
Where the use ofbleach.cleanusually ensures that there's no XSS vulnerability.
Although it is not recommended, you may also use this setting to whitelist otherkinds of calls, e.g. calls to i18n translation functions, where how safe that iswill depend on the implementation and how well the translations are audited.
Another common use-case is to wrap the output of functions that generate markuplikexml.etree.ElementTree.tostringor template rendering engines where sanitization of potential user input is eitheralready baked in or has to happen before rendering.
Default value:[]
Type:list[str]
Example usage:
check-typed-exception
Whether to disallowtry-except-pass (S110) for specificexception types. By default,try-except-pass is onlydisallowed forException andBaseException.
Default value:false
Type:bool
Example usage:
extend-markup-names
A list of additional callable names that behave likemarkupsafe.Markup.
Expects to receive a list of fully-qualified names (e.g.,webhelpers.html.literal, rather thanliteral).
Default value:[]
Type:list[str]
Example usage:
hardcoded-tmp-directory
A list of directories to consider temporary (seeS108).
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 thosespecified byhardcoded-tmp-directory (seeS108).
Default value:[]
Type:list[str]
Example usage:
lint.flake8-boolean-trap
Options for theflake8-boolean-trap plugin
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 thanField).
Default value:[]
Type:list[str]
Example usage:
lint.flake8-bugbear
Options for theflake8-bugbear plugin.
extend-immutable-calls
Additional callable functions to consider "immutable" when evaluating, e.g., thefunction-call-in-default-argument rule (B008) orfunction-call-in-dataclass-defaultsrule (RUF009).
Expects to receive a list of fully-qualified names (e.g.,fastapi.Query, rather thanQuery).
Default value:[]
Type:list[str]
Example usage:
lint.flake8-builtins
Options for theflake8-builtins plugin.
allowed-modules
List of builtin module names to allow.
Default value:[]
Type:list[str]
Example usage:
builtins-allowed-modules
Deprecated
This option has been deprecated in 0.10.0.builtins-allowed-modules has been renamed toallowed-modules. Use that instead.
DEPRECATED: This option has been renamed toallowed-modules. Useallowed-modules instead.
List of builtin module names to allow.
This option is ignored if bothallowed-modules andbuiltins-allowed-modules are set.
Default value:[]
Type:list[str]
Example usage:
builtins-ignorelist
Deprecated
This option has been deprecated in 0.10.0.builtins-ignorelist has been renamed toignorelist. Use that instead.
DEPRECATED: This option has been renamed toignorelist. Useignorelist instead.
Ignore list of builtins.
This option is ignored if bothignorelist andbuiltins-ignorelist are set.
Default value:[]
Type:list[str]
Example usage:
builtins-strict-checking
Deprecated
This option has been deprecated in 0.10.0.builtins-strict-checking has been renamed tostrict-checking. Use that instead.
DEPRECATED: This option has been renamed tostrict-checking. Usestrict-checking instead.
Compare module names instead of full module paths.
This option is ignored if bothstrict-checking andbuiltins-strict-checking are set.
Default value:false
Type:bool
Example usage:
ignorelist
Ignore list of builtins.
Default value:[]
Type:list[str]
Example usage:
strict-checking
Compare module names instead of full module paths.
Used byA005 -stdlib-module-shadowing.
Default value:false
Type:bool
Example usage:
lint.flake8-comprehensions
Options for theflake8-comprehensions plugin.
allow-dict-calls-with-keyword-arguments
Allowdict calls that make use of keyword arguments (e.g.,dict(a=1, b=2)).
Default value:false
Type:bool
Example usage:
lint.flake8-copyright
Options for theflake8-copyright plugin.
author
Author to enforce within the copyright notice. If provided, theauthor 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 tobe 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, compiledwith theregex crate.Defaults to(?i)Copyright\s+((?:\(C\)|©)\s+)?\d{4}((-|,\s)\d{4})*, which matchesthe 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
Options for theflake8-errmsg plugin.
max-string-length
Maximum string length for string literals in exception messages.
Default value:0
Type:int
Example usage:
lint.flake8-gettext
Options for theflake8-gettext plugin.
extend-function-names
Additional function names to consider as internationalization calls, in addition to thoseincluded infunction-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
Options for theflake8-implicit-str-concat plugin
allow-multiline
Whether to allow implicit string concatenations for multiline strings.By default, implicit concatenations of multiline strings areallowed (but continuation lines, delimited with a backslash, areprohibited).
Settingallow-multiline = false will automatically disable theexplicit-string-concatenation (ISC003) rule. Otherwise, bothimplicit and explicit multiline string concatenations would be seenas violations, making it impossible to write a linter-compliant multilinestring.
Default value:true
Type:bool
Example usage:
lint.flake8-import-conventions
Options for theflake8-import-conventions plugin
aliases
The conventional aliases for imports. These aliases can be extended bytheextend-aliases option.
Default value:{"altair": "alt", "matplotlib": "mpl", "matplotlib.pyplot": "plt", "numpy": "np", "numpy.typing": "npt", "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 thefrom ... import ... syntax.
For example, givenbanned-from = ["pandas"],from pandas import DataFramewould be disallowed, whileimport pandas would be allowed.
Default value:[]
Type:list[str]
Example usage:
extend-aliases
A mapping from module to conventional import alias. These aliases willbe added to thealiases mapping.
Default value:{}
Type:dict[str, str]
Example usage:
lint.flake8-pytest-style
Options for theflake8-pytest-style plugin
fixture-parentheses
Boolean flag specifying whether@pytest.fixture() without parametersshould have parentheses. If the option is set tofalse (the default),@pytest.fixture is valid and@pytest.fixture() is invalid. If settotrue,@pytest.fixture() is valid and@pytest.fixture isinvalid.
Default value:false
Type:bool
Example usage:
mark-parentheses
Boolean flag specifying whether@pytest.mark.foo() without parametersshould have parentheses. If the option is set tofalse (thedefault),@pytest.mark.foo is valid and@pytest.mark.foo() isinvalid. If set totrue,@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 incase 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 apytest.raises() call. This extends the default list of exceptionsthat require a match= parameter.This option is useful if you want to extend the default list ofexceptions that require a match= parameter without having to specifythe entire list.Note that this option does not remove any exceptions from the defaultlist.
Supports glob patterns. For more information on the glob syntax, referto theglobset documentation.
Default value:[]
Type:list[str]
Example usage:
raises-require-match-for
List of exception names that require a match= parameter in apytest.raises() call.
Supports glob patterns. For more information on the glob syntax, referto theglobset documentation.
Default value:["BaseException", "Exception", "ValueError", "OSError", "IOError", "EnvironmentError", "socket.error"]
Type:list[str]
Example usage:
warns-extend-require-match-for
List of additional warning names that require a match= parameter in apytest.warns() call. This extends the default list of warnings thatrequire a match= parameter.
This option is useful if you want to extend the default list of warningsthat require a match= parameter without having to specify the entirelist.
Note that this option does not remove any warnings from the defaultlist.
Supports glob patterns. For more information on the glob syntax, referto theglobset documentation.
Default value:[]
Type:list[str]
Example usage:
warns-require-match-for
List of warning names that require a match= parameter in apytest.warns() call.
Supports glob patterns. For more information on the glob syntax, referto theglobset documentation.
Default value:["Warning", "UserWarning", "DeprecationWarning"]
Type:list[str]
Example usage:
lint.flake8-quotes
Options for theflake8-quotes plugin.
avoid-escape
Whether to avoid using single quotes if a string contains single quotes,or vice-versa with double quotes, as perPEP 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 formatterenforces 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 thatformat.quote-style is set tothe 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 formatterenforces double quotes for multiline strings.
Default value:"double"
Type:"single" | "double"
Example usage:
lint.flake8-self
Options for theflake8_self plugin.
extend-ignore-names
Additional names to ignore when consideringflake8-self violations,in addition to those included inignore-names.
Default value:[]
Type:list[str]
Example usage:
ignore-names
A list of names to ignore when consideringflake8-self violations.
Default value:["_make", "_asdict", "_replace", "_fields", "_field_defaults", "_name_", "_value_"]
Type:list[str]
Example usage:
lint.flake8-tidy-imports
Options for theflake8-tidy-imports plugin
ban-relative-imports
Whether to ban all relative imports ("all"), or only those importsthat 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 viaeval orimportlib.
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 beimported lazily (e.g., within a function definition, or anif TYPE_CHECKING:block, or some other nested context). This also affects the ruleimport-outside-top-levelifbanned-module-level-imports is enabled.
Default value:[]
Type:list[str]
Example usage:
lint.flake8-type-checking
Options for theflake8-type-checking plugin
exempt-modules
Exempt certain modules from needing to be moved into type-checkingblocks.
Default value:["typing"]
Type:list[str]
Example usage:
quote-annotations
Whether to add quotes around type annotations, if doing so would allowthe corresponding import to be moved into a type-checking block.
For example, in the following, Python requires thatSequence beavailable at runtime, despite the fact that it's only used in a typeannotation:
In other words, movingfrom collections.abc import Sequence into anif TYPE_CHECKING: block above would cause a runtime error, as thetype would no longer be available at runtime.
By default, Ruff will respect such runtime semantics and avoid movingthe import to prevent such runtime errors.
Settingquote-annotations totrue will instruct Ruff to add quotesaround the annotation (e.g.,"Sequence[int]"), which in turn enablesRuff to move the import into anif TYPE_CHECKING: block, like so:
fromtypingimportTYPE_CHECKINGifTYPE_CHECKING:fromcollections.abcimportSequencedeffunc(value:"Sequence[int]")->None:...Note that this setting has no effect whenfrom __future__ import annotationsis present, as__future__ annotations are always treated equivalentlyto 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 classfrom needing to be moved into type-checking blocks.
Common examples include Pydantic'spydantic.BaseModel and SQLAlchemy'ssqlalchemy.orm.DeclarativeBase, but can also support user-definedclasses that inherit from those base classes. For example, if you definea commonDeclarativeBase subclass that's used throughout your project(e.g.,class Base(DeclarativeBase) ... inbase.py), you can add it tothis list (runtime-evaluated-base-classes = ["base.Base"]) to exemptmodels 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 enumerateddecorators from being moved into type-checking blocks.
Common examples include Pydantic's@pydantic.validate_call decorator(for functions) and attrs'@attrs.define decorator (for classes).
This also supports framework decorators like FastAPI'sfastapi.FastAPI.getwhich will work across assignments in the same module.
For example:
Hereapp.get will correctly be identified asfastapi.FastAPI.get.
Default value:[]
Type:list[str]
Example usage:
strict
EnforceTC001,TC002, andTC003 rules even when valid runtime importsare present for the same module.
See flake8-type-checking'sstrict option.
Default value:false
Type:bool
Example usage:
lint.flake8-unused-arguments
Options for theflake8-unused-arguments plugin
ignore-variadic-names
Whether to allow unused variadic arguments, like*args and**kwargs.
Default value:false
Type:bool
Example usage:
lint.isort
Options for theisort plugin.
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 fororder-by-type regardless of casing.
Default value:[]
Type:list[str]
Example usage:
combine-as-imports
Combines as imports on the same line. See isort'scombine-as-importsoption.
Default value:false
Type:bool
Example usage:
constants
An override list of tokens to always recognize as a CONSTANTfororder-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 specifiedsection-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, whendetect-same-package = true, then when analyzing files within thefoo package, any imports from within thefoo package will be considered first-party.
This heuristic is often unnecessary whensrc is configured to detect all first-partysources; however, ifsrc isnot configured, this heuristic can be useful to detectfirst-party imports fromwithin (but notacross) first-party packages.
Default value:true
Type:bool
Example usage:
extra-standard-library
A list of modules to consider standard-library, in addition to thoseknown to Ruff in advance.
Supports glob patterns. For more information on the glob syntax, referto theglobset 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 (likeimport sys) before from-styleimports (likefrom itertools import groupby). Instead, sort theimports 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
Forceimport from statements with multiple members and at least onealias (e.g.,import A as B) to wrap such that every line containsexactly 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 withcombine-as-imports = true. Whencombine-as-imports isn'tenabled, every aliasedimport from will be given its own line, inwhich case, wrapping is not necessary.
When using the formatter, ensure thatformat.skip-magic-trailing-comma is set tofalse (default)when enablingforce-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 placeimport from imports before straight imports when sorting.
For example, by default, imports will be sorted such that straight imports appearbeforeimport from imports, as in:
Settingfrom-first = true will instead sort such thatimport from imports appearbefore 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 theycan be identified as such via introspection of the local filesystem.
Supports glob patterns. For more information on the glob syntax, referto theglobset 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, referto theglobset documentation.
Default value:[]
Type:list[str]
Example usage:
known-third-party
A list of modules to consider third-party, regardless of whether theycan be identified as such via introspection of the local filesystem.
Supports glob patterns. For more information on the glob syntax, referto theglobset documentation.
Default value:[]
Type:list[str]
Example usage:
length-sort
Sort imports by their string length, such that shorter imports appearbefore longer imports. For example, by default, imports will be sortedalphabetically, as in:
Settinglength-sort = true will instead sort such that shorter importsappear before longer imports, as in:
Default value:false
Type:bool
Example usage:
length-sort-straight
Sort straight imports by their string length. Similar tolength-sort,but applies only to straight imports and doesn't affectfrom 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 tothe typing style recommendations (source).
When using the formatter, only the values-1,1, and2 are compatible becauseit 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" andimport from imports.
When using the formatter, only the values0 and1 are compatible becauseit 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 shouldnot be delineated from the previoussection 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:
Settingno-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 toalphabetically.
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 viceversa.
The default ("furthest-to-closest") is equivalent to isort'sreverse-relative default (reverse-relative = false); settingthis to "closest-to-furthest" is equivalent to isort'sreverse-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 oroverride the built-in sections.
For example, to group all testing utilities, you could create atesting section:
The values in the list are treated as glob patterns. For example, to match all packages inthe LangChain ecosystem (langchain-core,langchain-openai, etc.):
Custom sections should typically be inserted into thesection-order list to ensure thatthey're displayed as a standalone group and in the intended order, as in:
If a custom section is omitted fromsection-order, imports in that section will beassigned to thedefault-section (which defaults tothird-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, thenthe imports will never be folded into one line.
See isort'ssplit-on-trailing-comma option.
When using the formatter, ensure thatformat.skip-magic-trailing-comma is set tofalse (default) when enablingsplit-on-trailing-commato 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 varfororder-by-type regardless of casing.
Default value:[]
Type:list[str]
Example usage:
lint.mccabe
Options for themccabe plugin.
max-complexity
The maximum McCabe complexity to allow before triggeringC901 errors.
Default value:10
Type:int
Example usage:
lint.pep8-naming
Options for thepep8-naming plugin.
classmethod-decorators
A list of decorators that, when applied to a method, indicate that themethod should be treated as a class method (in addition to the builtin@classmethod).
For example, Ruff will expect that any method decorated by a decoratorin this list takes acls argument as its first argument.
Expects to receive a list of fully-qualified names (e.g.,pydantic.validator,rather thanvalidator) or alternatively a plain name which is then matched againstthe last segment in case the decorator itself consists of a dotted name.
Default value:[]
Type:list[str]
Example usage:
extend-ignore-names
Additional names (or patterns) to ignore when consideringpep8-naming violations,in addition to those included inignore-names.
Supports glob patterns. For example, to ignore all names starting withtest_or ending with_test, you could useignore-names = ["test_*", "*_test"].For more information on the glob syntax, refer to theglobset documentation.
Default value:[]
Type:list[str]
Example usage:
ignore-names
A list of names (or patterns) to ignore when consideringpep8-naming violations.
Supports glob patterns. For example, to ignore all names starting withtest_or ending with_test, you could useignore-names = ["test_*", "*_test"].For more information on the glob syntax, refer to theglobset 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 themethod should be treated as a static method (in addition to the builtin@staticmethod).
For example, Ruff will expect that any method decorated by a decoratorin this list has noself orcls argument.
Expects to receive a list of fully-qualified names (e.g.,belay.Device.teardown,rather thanteardown) or alternatively a plain name which is then matched againstthe last segment in case the decorator itself consists of a dotted name.
Default value:[]
Type:list[str]
Example usage:
lint.pycodestyle
Options for thepycodestyle plugin.
ignore-overlong-task-comments
Whether line-length violations (E501) should be triggered forcomments starting withtask-tags (by default: "TODO", "FIXME",and "XXX").
Default value:false
Type:bool
Example usage:
max-doc-length
The maximum line length to allow fordoc-line-too-long violations withindocumentation (W505), including standalone comments. By default,this is set tonull 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, theunicode width of each character is added up to determine the length.
See thedoc-line-too-long rule for more information.
Default value:null
Type:int
Example usage:
max-line-length
The maximum line length to allow forline-too-long violations. By default,this is set to the value of theline-length option.
Use this option when you want to detect extra-long lines that the formatter can't automatically split by settingpycodestyle.line-length to a value larger thanline-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=100The length is determined by the number of characters per line, except for lines containing East Asian characters or emojis.For these lines, theunicode width of each character is added up to determine the length.
See theline-too-long rule for more information.
Default value:null
Type:int
Example usage:
lint.pydoclint
Options for thepydoclint plugin.
ignore-one-line-docstrings
Skip docstrings which fit on a single line.
Note: The corresponding setting inpydoclintis namedskip-checking-short-docstrings.
Default value:false
Type:bool
Example usage:
lint.pydocstyle
Options for thepydocstyle plugin.
convention
Whether to use Google-style, NumPy-style conventions, or thePEP 257defaults when analyzing docstring sections.
Enabling a convention will disable all rules that are not included inthe specified convention. As such, the intended workflow is to enable aconvention and then selectively enable or disable any additional ruleson top of it.
For example, to use Google-style conventions but avoid requiringdocumentation 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 ofD4 orD40):
[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 thespecified fully-qualified decorators.
Default value:[]
Type:list[str]
Example usage:
ignore-var-parameters
If set totrue, ignore missing documentation for*args and**kwargs parameters.
Default value:false
Type:bool
Example usage:
property-decorators
A list of decorators that, when applied to a method, indicate that themethod 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 decoratorin this list can use a non-imperative summary line.
Default value:[]
Type:list[str]
Example usage:
lint.pyflakes
Options for thepyflakes plugin.
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 onimport (e.g.,hvplot.pandas).
Modules in this list are expected to be fully-qualified names (e.g.,hvplot.pandas). Anysubmodule of a given module will also be ignored (e.g., givenhvplot,hvplot.pandaswill also be ignored).
Default value:[]
Type:list[str]
Example usage:
extend-generics
Additional functions or classes to consider generic, such that anysubscripts should be treated as type annotation (e.g.,ForeignKey indjango.db.models.ForeignKey["User"].
Expects to receive a list of fully-qualified names (e.g.,django.db.models.ForeignKey,rather thanForeignKey).
Default value:[]
Type:list[str]
Example usage:
lint.pylint
Options for thepylint plugin.
allow-dunder-method-names
Dunder methods name to allow, in addition to the default set from thePython standard library (seePLW3201).
Default value:[]
Type:list[str]
Example usage:
allow-magic-value-types
Constant types to ignore when used as "magic values" (seePLR2004).
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(seePLR0913).
Default value:5
Type:int
Example usage:
max-bool-expr
Maximum number of Boolean expressions allowed within a singleif statement(seePLR0916).
Default value:5
Type:int
Example usage:
max-branches
Maximum number of branches allowed for a function or method body (seePLR0912).
Default value:12
Type:int
Example usage:
max-locals
Maximum number of local variables allowed for a function or method body (seePLR0914).
Default value:15
Type:int
Example usage:
max-nested-blocks
Maximum number of nested blocks allowed within a function or method body(seePLR1702).
Default value:5
Type:int
Example usage:
max-positional-args
Maximum number of positional arguments allowed for a function or method definition(seePLR0917).
If not specified, defaults to the value ofmax-args.
Default value:5
Type:int
Example usage:
max-public-methods
Maximum number of public methods allowed for a class (seePLR0904).
Default value:20
Type:int
Example usage:
max-returns
Maximum number of return statements allowed for a function or methodbody (seePLR0911)
Default value:6
Type:int
Example usage:
max-statements
Maximum number of statements allowed for a function or method body (seePLR0915).
Default value:50
Type:int
Example usage:
lint.pyupgrade
Options for thepyupgrade plugin.
keep-runtime-typing
Whether to avoidPEP 585 (List[int] ->list[int]) andPEP 604(Union[str, int] ->str | int) rewrites even if a file importsfrom __future__ import annotations.
This setting is only applicable when the target Python version is below3.9 and 3.10 respectively, and is most commonly used when working withlibraries like Pydantic and FastAPI, which rely on the ability to parsetype annotations at runtime. The use offrom __future__ import annotationscauses Python to treat the type annotations as strings, which typicallyallows for the use of language features that appear in later Pythonversions but are not yet supported by the current version (e.g.,str |int). However, libraries that rely on runtime type annotations willbreak if the annotations are incompatible with the current Pythonversion.
For example, while the following is valid Python 3.8 code due to thepresence offrom __future__ import annotations, the use ofstr | intprior to Python 3.10 will cause Pydantic to raise aTypeError atruntime:
Default value:false
Type:bool
Example usage:
lint.ruff
Options for theruff plugin
allowed-markup-calls
Deprecated
This option has been deprecated in 0.10.0. Theallowed-markup-names option has been moved to theflake8-bandit section of the configuration.
A list of callable names, whose result may be safely passed intomarkupsafe.Markup.
Expects to receive a list of fully-qualified names (e.g.,bleach.clean, rather thanclean).
This setting helps you avoid false positives in code like:
Where the use ofbleach.cleanusually ensures that there's no XSS vulnerability.
Although it is not recommended, you may also use this setting to whitelist otherkinds of calls, e.g. calls to i18n translation functions, where how safe that iswill depend on the implementation and how well the translations are audited.
Another common use-case is to wrap the output of functions that generate markuplikexml.etree.ElementTree.tostringor template rendering engines where sanitization of potential user input is eitheralready baked in or has to happen before rendering.
Default value:[]
Type:list[str]
Example usage:
extend-markup-names
Deprecated
This option has been deprecated in 0.10.0. Theextend-markup-names option has been moved to theflake8-bandit section of the configuration.
A list of additional callable names that behave likemarkupsafe.Markup.
Expects to receive a list of fully-qualified names (e.g.,webhelpers.html.literal, rather thanliteral).
Default value:[]
Type:list[str]
Example usage:
parenthesize-tuple-in-subscript
Whether to prefer accessing items keyed by tuples withparentheses around the tuple (seeRUF031).
Default value:false
Type:bool
Example usage: