Configuring Ruff | Ruff (original) (raw)

Ruff can be configured through a pyproject.toml, ruff.toml, or .ruff.toml file.

Whether you're using Ruff as a linter, formatter, or both, the underlying configuration strategy and semantics are the same.

For a complete enumeration of the available configuration options, see Settings.

If left unspecified, Ruff's default configuration is equivalent to:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-0-1)[tool.ruff] [](#%5F%5Fcodelineno-0-2)# Exclude a variety of commonly ignored directories. [](#%5F%5Fcodelineno-0-3)exclude = [ [](#%5F%5Fcodelineno-0-4) ".bzr", [](#%5F%5Fcodelineno-0-5) ".direnv", [](#%5F%5Fcodelineno-0-6) ".eggs", [](#%5F%5Fcodelineno-0-7) ".git", [](#%5F%5Fcodelineno-0-8) ".git-rewrite", [](#%5F%5Fcodelineno-0-9) ".hg", [](#%5F%5Fcodelineno-0-10) ".ipynb_checkpoints", [](#%5F%5Fcodelineno-0-11) ".mypy_cache", [](#%5F%5Fcodelineno-0-12) ".nox", [](#%5F%5Fcodelineno-0-13) ".pants.d", [](#%5F%5Fcodelineno-0-14) ".pyenv", [](#%5F%5Fcodelineno-0-15) ".pytest_cache", [](#%5F%5Fcodelineno-0-16) ".pytype", [](#%5F%5Fcodelineno-0-17) ".ruff_cache", [](#%5F%5Fcodelineno-0-18) ".svn", [](#%5F%5Fcodelineno-0-19) ".tox", [](#%5F%5Fcodelineno-0-20) ".venv", [](#%5F%5Fcodelineno-0-21) ".vscode", [](#%5F%5Fcodelineno-0-22) "__pypackages__", [](#%5F%5Fcodelineno-0-23) "_build", [](#%5F%5Fcodelineno-0-24) "buck-out", [](#%5F%5Fcodelineno-0-25) "build", [](#%5F%5Fcodelineno-0-26) "dist", [](#%5F%5Fcodelineno-0-27) "node_modules", [](#%5F%5Fcodelineno-0-28) "site-packages", [](#%5F%5Fcodelineno-0-29) "venv", [](#%5F%5Fcodelineno-0-30)] [](#%5F%5Fcodelineno-0-31) [](#%5F%5Fcodelineno-0-32)# Same as Black. [](#%5F%5Fcodelineno-0-33)line-length = 88 [](#%5F%5Fcodelineno-0-34)indent-width = 4 [](#%5F%5Fcodelineno-0-35) [](#%5F%5Fcodelineno-0-36)# Assume Python 3.9 [](#%5F%5Fcodelineno-0-37)target-version = "py39" [](#%5F%5Fcodelineno-0-38) [](#%5F%5Fcodelineno-0-39)[tool.ruff.lint] [](#%5F%5Fcodelineno-0-40)# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`) codes by default. [](#%5F%5Fcodelineno-0-41)# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or [](#%5F%5Fcodelineno-0-42)# McCabe complexity (`C901`) by default. [](#%5F%5Fcodelineno-0-43)select = ["E4", "E7", "E9", "F"] [](#%5F%5Fcodelineno-0-44)ignore = [] [](#%5F%5Fcodelineno-0-45) [](#%5F%5Fcodelineno-0-46)# Allow fix for all enabled rules (when `--fix`) is provided. [](#%5F%5Fcodelineno-0-47)fixable = ["ALL"] [](#%5F%5Fcodelineno-0-48)unfixable = [] [](#%5F%5Fcodelineno-0-49) [](#%5F%5Fcodelineno-0-50)# Allow unused variables when underscore-prefixed. [](#%5F%5Fcodelineno-0-51)dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$" [](#%5F%5Fcodelineno-0-52) [](#%5F%5Fcodelineno-0-53)[tool.ruff.format] [](#%5F%5Fcodelineno-0-54)# Like Black, use double quotes for strings. [](#%5F%5Fcodelineno-0-55)quote-style = "double" [](#%5F%5Fcodelineno-0-56) [](#%5F%5Fcodelineno-0-57)# Like Black, indent with spaces, rather than tabs. [](#%5F%5Fcodelineno-0-58)indent-style = "space" [](#%5F%5Fcodelineno-0-59) [](#%5F%5Fcodelineno-0-60)# Like Black, respect magic trailing commas. [](#%5F%5Fcodelineno-0-61)skip-magic-trailing-comma = false [](#%5F%5Fcodelineno-0-62) [](#%5F%5Fcodelineno-0-63)# Like Black, automatically detect the appropriate line ending. [](#%5F%5Fcodelineno-0-64)line-ending = "auto" [](#%5F%5Fcodelineno-0-65) [](#%5F%5Fcodelineno-0-66)# Enable auto-formatting of code examples in docstrings. Markdown, [](#%5F%5Fcodelineno-0-67)# reStructuredText code/literal blocks and doctests are all supported. [](#%5F%5Fcodelineno-0-68)# [](#%5F%5Fcodelineno-0-69)# This is currently disabled by default, but it is planned for this [](#%5F%5Fcodelineno-0-70)# to be opt-out in the future. [](#%5F%5Fcodelineno-0-71)docstring-code-format = false [](#%5F%5Fcodelineno-0-72) [](#%5F%5Fcodelineno-0-73)# Set the line length limit used when formatting code snippets in [](#%5F%5Fcodelineno-0-74)# docstrings. [](#%5F%5Fcodelineno-0-75)# [](#%5F%5Fcodelineno-0-76)# This only has an effect when the `docstring-code-format` setting is [](#%5F%5Fcodelineno-0-77)# enabled. [](#%5F%5Fcodelineno-0-78)docstring-code-line-length = "dynamic"

[](#%5F%5Fcodelineno-1-1)# Exclude a variety of commonly ignored directories. [](#%5F%5Fcodelineno-1-2)exclude = [ [](#%5F%5Fcodelineno-1-3) ".bzr", [](#%5F%5Fcodelineno-1-4) ".direnv", [](#%5F%5Fcodelineno-1-5) ".eggs", [](#%5F%5Fcodelineno-1-6) ".git", [](#%5F%5Fcodelineno-1-7) ".git-rewrite", [](#%5F%5Fcodelineno-1-8) ".hg", [](#%5F%5Fcodelineno-1-9) ".ipynb_checkpoints", [](#%5F%5Fcodelineno-1-10) ".mypy_cache", [](#%5F%5Fcodelineno-1-11) ".nox", [](#%5F%5Fcodelineno-1-12) ".pants.d", [](#%5F%5Fcodelineno-1-13) ".pyenv", [](#%5F%5Fcodelineno-1-14) ".pytest_cache", [](#%5F%5Fcodelineno-1-15) ".pytype", [](#%5F%5Fcodelineno-1-16) ".ruff_cache", [](#%5F%5Fcodelineno-1-17) ".svn", [](#%5F%5Fcodelineno-1-18) ".tox", [](#%5F%5Fcodelineno-1-19) ".venv", [](#%5F%5Fcodelineno-1-20) ".vscode", [](#%5F%5Fcodelineno-1-21) "__pypackages__", [](#%5F%5Fcodelineno-1-22) "_build", [](#%5F%5Fcodelineno-1-23) "buck-out", [](#%5F%5Fcodelineno-1-24) "build", [](#%5F%5Fcodelineno-1-25) "dist", [](#%5F%5Fcodelineno-1-26) "node_modules", [](#%5F%5Fcodelineno-1-27) "site-packages", [](#%5F%5Fcodelineno-1-28) "venv", [](#%5F%5Fcodelineno-1-29)] [](#%5F%5Fcodelineno-1-30) [](#%5F%5Fcodelineno-1-31)# Same as Black. [](#%5F%5Fcodelineno-1-32)line-length = 88 [](#%5F%5Fcodelineno-1-33)indent-width = 4 [](#%5F%5Fcodelineno-1-34) [](#%5F%5Fcodelineno-1-35)# Assume Python 3.9 [](#%5F%5Fcodelineno-1-36)target-version = "py39" [](#%5F%5Fcodelineno-1-37) [](#%5F%5Fcodelineno-1-38)[lint] [](#%5F%5Fcodelineno-1-39)# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`) codes by default. [](#%5F%5Fcodelineno-1-40)# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or [](#%5F%5Fcodelineno-1-41)# McCabe complexity (`C901`) by default. [](#%5F%5Fcodelineno-1-42)select = ["E4", "E7", "E9", "F"] [](#%5F%5Fcodelineno-1-43)ignore = [] [](#%5F%5Fcodelineno-1-44) [](#%5F%5Fcodelineno-1-45)# Allow fix for all enabled rules (when `--fix`) is provided. [](#%5F%5Fcodelineno-1-46)fixable = ["ALL"] [](#%5F%5Fcodelineno-1-47)unfixable = [] [](#%5F%5Fcodelineno-1-48) [](#%5F%5Fcodelineno-1-49)# Allow unused variables when underscore-prefixed. [](#%5F%5Fcodelineno-1-50)dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$" [](#%5F%5Fcodelineno-1-51) [](#%5F%5Fcodelineno-1-52)[format] [](#%5F%5Fcodelineno-1-53)# Like Black, use double quotes for strings. [](#%5F%5Fcodelineno-1-54)quote-style = "double" [](#%5F%5Fcodelineno-1-55) [](#%5F%5Fcodelineno-1-56)# Like Black, indent with spaces, rather than tabs. [](#%5F%5Fcodelineno-1-57)indent-style = "space" [](#%5F%5Fcodelineno-1-58) [](#%5F%5Fcodelineno-1-59)# Like Black, respect magic trailing commas. [](#%5F%5Fcodelineno-1-60)skip-magic-trailing-comma = false [](#%5F%5Fcodelineno-1-61) [](#%5F%5Fcodelineno-1-62)# Like Black, automatically detect the appropriate line ending. [](#%5F%5Fcodelineno-1-63)line-ending = "auto" [](#%5F%5Fcodelineno-1-64) [](#%5F%5Fcodelineno-1-65)# Enable auto-formatting of code examples in docstrings. Markdown, [](#%5F%5Fcodelineno-1-66)# reStructuredText code/literal blocks and doctests are all supported. [](#%5F%5Fcodelineno-1-67)# [](#%5F%5Fcodelineno-1-68)# This is currently disabled by default, but it is planned for this [](#%5F%5Fcodelineno-1-69)# to be opt-out in the future. [](#%5F%5Fcodelineno-1-70)docstring-code-format = false [](#%5F%5Fcodelineno-1-71) [](#%5F%5Fcodelineno-1-72)# Set the line length limit used when formatting code snippets in [](#%5F%5Fcodelineno-1-73)# docstrings. [](#%5F%5Fcodelineno-1-74)# [](#%5F%5Fcodelineno-1-75)# This only has an effect when the `docstring-code-format` setting is [](#%5F%5Fcodelineno-1-76)# enabled. [](#%5F%5Fcodelineno-1-77)docstring-code-line-length = "dynamic"

As an example, the following would configure Ruff to:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-2-1)[tool.ruff.lint] [](#%5F%5Fcodelineno-2-2)# 1. Enable flake8-bugbear (`B`) rules, in addition to the defaults. [](#%5F%5Fcodelineno-2-3)select = ["E4", "E7", "E9", "F", "B"] [](#%5F%5Fcodelineno-2-4) [](#%5F%5Fcodelineno-2-5)# 2. Avoid enforcing line-length violations (`E501`) [](#%5F%5Fcodelineno-2-6)ignore = ["E501"] [](#%5F%5Fcodelineno-2-7) [](#%5F%5Fcodelineno-2-8)# 3. Avoid trying to fix flake8-bugbear (`B`) violations. [](#%5F%5Fcodelineno-2-9)unfixable = ["B"] [](#%5F%5Fcodelineno-2-10) [](#%5F%5Fcodelineno-2-11)# 4. Ignore `E402` (import violations) in all `__init__.py` files, and in selected subdirectories. [](#%5F%5Fcodelineno-2-12)[tool.ruff.lint.per-file-ignores] [](#%5F%5Fcodelineno-2-13)"__init__.py" = ["E402"] [](#%5F%5Fcodelineno-2-14)"**/{tests,docs,tools}/*" = ["E402"] [](#%5F%5Fcodelineno-2-15) [](#%5F%5Fcodelineno-2-16)[tool.ruff.format] [](#%5F%5Fcodelineno-2-17)# 5. Use single quotes in `ruff format`. [](#%5F%5Fcodelineno-2-18)quote-style = "single"

[](#%5F%5Fcodelineno-3-1)[lint] [](#%5F%5Fcodelineno-3-2)# 1. Enable flake8-bugbear (`B`) rules, in addition to the defaults. [](#%5F%5Fcodelineno-3-3)select = ["E4", "E7", "E9", "F", "B"] [](#%5F%5Fcodelineno-3-4) [](#%5F%5Fcodelineno-3-5)# 2. Avoid enforcing line-length violations (`E501`) [](#%5F%5Fcodelineno-3-6)ignore = ["E501"] [](#%5F%5Fcodelineno-3-7) [](#%5F%5Fcodelineno-3-8)# 3. Avoid trying to fix flake8-bugbear (`B`) violations. [](#%5F%5Fcodelineno-3-9)unfixable = ["B"] [](#%5F%5Fcodelineno-3-10) [](#%5F%5Fcodelineno-3-11)# 4. Ignore `E402` (import violations) in all `__init__.py` files, and in selected subdirectories. [](#%5F%5Fcodelineno-3-12)[lint.per-file-ignores] [](#%5F%5Fcodelineno-3-13)"__init__.py" = ["E402"] [](#%5F%5Fcodelineno-3-14)"**/{tests,docs,tools}/*" = ["E402"] [](#%5F%5Fcodelineno-3-15) [](#%5F%5Fcodelineno-3-16)[format] [](#%5F%5Fcodelineno-3-17)# 5. Use single quotes in `ruff format`. [](#%5F%5Fcodelineno-3-18)quote-style = "single"

Linter plugin configurations are expressed as subsections, e.g.:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-4-1)[tool.ruff.lint] [](#%5F%5Fcodelineno-4-2)# Add "Q" to the list of enabled codes. [](#%5F%5Fcodelineno-4-3)select = ["E4", "E7", "E9", "F", "Q"] [](#%5F%5Fcodelineno-4-4) [](#%5F%5Fcodelineno-4-5)[tool.ruff.lint.flake8-quotes] [](#%5F%5Fcodelineno-4-6)docstring-quotes = "double"

[](#%5F%5Fcodelineno-5-1)[lint] [](#%5F%5Fcodelineno-5-2)# Add "Q" to the list of enabled codes. [](#%5F%5Fcodelineno-5-3)select = ["E4", "E7", "E9", "F", "Q"] [](#%5F%5Fcodelineno-5-4) [](#%5F%5Fcodelineno-5-5)[lint.flake8-quotes] [](#%5F%5Fcodelineno-5-6)docstring-quotes = "double"

Ruff respects pyproject.toml, ruff.toml, and .ruff.toml files. All three implement an equivalent schema (though in the ruff.toml and .ruff.toml versions, the [tool.ruff] header andtool.ruff section prefix is omitted).

For a complete enumeration of the available configuration options, see Settings.

Config file discovery

Similar to ESLint, Ruff supports hierarchical configuration, such that the "closest" config file in the directory hierarchy is used for every individual file, with all paths in the config file (e.g., exclude globs, src paths) being resolved relative to the directory containing that config file.

There are a few exceptions to these rules:

In locating the "closest" pyproject.toml file for a given path, Ruff ignores anypyproject.toml files that lack a [tool.ruff] section.
If a configuration file is passed directly via --config, those settings are used for all analyzed files, and any relative paths in that configuration file (like exclude globs orsrc paths) are resolved relative to the current working directory.
If no config file is found in the filesystem hierarchy, Ruff will fall back to using a default configuration. If a user-specific configuration file exists at ${config_dir}/ruff/pyproject.toml, that file will be used instead of the default configuration, with ${config_dir} being determined via etcetera's native strategy, and all relative paths being again resolved relative to the current working directory.
Any config-file-supported settings that are provided on the command-line (e.g., via--select) will override the settings in every resolved configuration file.

Unlike ESLint, Ruff does not merge settings across configuration files; instead, the "closest" configuration file is used, and any parent configuration files are ignored. In lieu of this implicit cascade, Ruff supports an extend field, which allows you to inherit the settings from another config file, like so:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-6-1)[tool.ruff] [](#%5F%5Fcodelineno-6-2)# Extend the `pyproject.toml` file in the parent directory... [](#%5F%5Fcodelineno-6-3)extend = "../pyproject.toml" [](#%5F%5Fcodelineno-6-4) [](#%5F%5Fcodelineno-6-5)# ...but use a different line length. [](#%5F%5Fcodelineno-6-6)line-length = 100

[](#%5F%5Fcodelineno-7-1)# Extend the `ruff.toml` file in the parent directory... [](#%5F%5Fcodelineno-7-2)extend = "../ruff.toml" [](#%5F%5Fcodelineno-7-3) [](#%5F%5Fcodelineno-7-4)# ...but use a different line length. [](#%5F%5Fcodelineno-7-5)line-length = 100

All of the above rules apply equivalently to pyproject.toml, ruff.toml, and .ruff.toml files. If Ruff detects multiple configuration files in the same directory, the .ruff.toml file will take precedence over the ruff.toml file, and the ruff.toml file will take precedence over the pyproject.toml file.

Inferring the Python version

When no discovered configuration specifies a target-version, Ruff will attempt to fall back to the minimum version compatible with the requires-python field in a nearby pyproject.toml. The rules for this behavior are as follows:

If a configuration file is passed directly, Ruff does not attempt to infer a missing target-version.
If a configuration file is found in the filesystem hierarchy, Ruff will infer a missing target-version from the requires-python field in a pyproject.toml file in the same directory as the found configuration.
If we are using a user-level configuration from ${config_dir}/ruff/pyproject.toml, the requires-python field in the first pyproject.toml file found in an ancestor of the current working directory takes precedence over the target-version in the user-level configuration.
If no configuration files are found, Ruff will infer the target-version from the requires-python field in the first pyproject.toml file found in an ancestor of the current working directory.

Note that in these last two cases, the behavior of Ruff may differ depending on the working directory from which it is invoked.

Python file discovery

When passed a path on the command-line, Ruff will automatically discover all Python files in that path, taking into account the exclude and extend-excludesettings in each directory's configuration file.

Files can also be selectively excluded from linting or formatting by scoping the exclude setting to the tool-specific configuration tables. For example, the following would prevent ruff from formatting .pyi files, but would continue to include them in linting:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-8-1)[tool.ruff.format] [](#%5F%5Fcodelineno-8-2)exclude = ["*.pyi"]

[](#%5F%5Fcodelineno-9-1)[format] [](#%5F%5Fcodelineno-9-2)exclude = ["*.pyi"]

By default, Ruff will also skip any files that are omitted via .ignore, .gitignore,.git/info/exclude, and global gitignore files (see: respect-gitignore).

Files that are passed to ruff directly are always analyzed, regardless of the above criteria. For example, ruff check /path/to/excluded/file.py will always lint file.py.

Default inclusions

By default, Ruff will discover files matching *.py, *.pyi, *.ipynb, or pyproject.toml.

To lint or format files with additional file extensions, use the extend-include setting. You can also change the default selection using the include setting.

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-10-1)[tool.ruff] [](#%5F%5Fcodelineno-10-2)include = ["pyproject.toml", "src/**/*.py", "scripts/**/*.py"]

[](#%5F%5Fcodelineno-11-1)include = ["pyproject.toml", "src/**/*.py", "scripts/**/*.py"]

Warning

Paths provided to include must match files. For example, include = ["src"] will fail since it matches a directory.

Jupyter Notebook discovery

Ruff has built-in support for linting and formatting Jupyter Notebooks, which are linted and formatted by default on version 0.6.0 and higher.

If you'd prefer to either only lint or only format Jupyter Notebook files, you can use the section-specific exclude option to do so. For example, the following would only lint Jupyter Notebook files and not format them:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-12-1)[tool.ruff.format] [](#%5F%5Fcodelineno-12-2)exclude = ["*.ipynb"]

[](#%5F%5Fcodelineno-13-1)[format] [](#%5F%5Fcodelineno-13-2)exclude = ["*.ipynb"]

And, conversely, the following would only format Jupyter Notebook files and not lint them:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-14-1)[tool.ruff.lint] [](#%5F%5Fcodelineno-14-2)exclude = ["*.ipynb"]

[](#%5F%5Fcodelineno-15-1)[lint] [](#%5F%5Fcodelineno-15-2)exclude = ["*.ipynb"]

You can completely disable Jupyter Notebook support by updating theextend-exclude setting:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-16-1)[tool.ruff] [](#%5F%5Fcodelineno-16-2)extend-exclude = ["*.ipynb"]

[](#%5F%5Fcodelineno-17-1)extend-exclude = ["*.ipynb"]

If you'd like to ignore certain rules specifically for Jupyter Notebook files, you can do so by using the per-file-ignores setting:

pyproject.tomlruff.toml

[](#%5F%5Fcodelineno-18-1)[tool.ruff.lint.per-file-ignores] [](#%5F%5Fcodelineno-18-2)"*.ipynb" = ["T20"]

[](#%5F%5Fcodelineno-19-1)[lint.per-file-ignores] [](#%5F%5Fcodelineno-19-2)"*.ipynb" = ["T20"]

Some rules have different behavior when applied to Jupyter Notebook files. For example, when applied to .py files themodule-import-not-at-top-of-file (E402)rule detect imports at the top of a file, but for notebooks it detects imports at the top of acell. For a given rule, the rule's documentation will always specify if it has different behavior when applied to Jupyter Notebook files.

Command-line interface

Some configuration options can be provided or overridden via dedicated flags on the command line. This includes those related to rule enablement and disablement, file discovery, logging level, and more:

[](#%5F%5Fcodelineno-20-1)$ ruff check path/to/code/ --select F401 --select F403 --quiet

All other configuration options can be set via the command line using the --config flag, detailed below.

The --config CLI flag

The --config flag has two uses. It is most often used to point to the configuration file that you would like Ruff to use, for example:

[](#%5F%5Fcodelineno-21-1)$ ruff check path/to/directory --config path/to/ruff.toml

However, the --config flag can also be used to provide arbitrary overrides of configuration settings using TOML <KEY> = <VALUE> pairs. This is mostly useful in situations where you wish to override a configuration setting that does not have a dedicated command-line flag.

In the below example, the --config flag is the only way of overriding thedummy-variable-rgx configuration setting from the command line, since this setting has no dedicated CLI flag. The per-file-ignores setting could also have been overridden via the --per-file-ignores dedicated flag, but using --config to override the setting is also fine:

[](#%5F%5Fcodelineno-22-1)$ ruff check path/to/file --config path/to/ruff.toml --config "lint.dummy-variable-rgx = '__.*'" --config "lint.per-file-ignores = {'some_file.py' = ['F841']}"

Configuration options passed to --config are parsed in the same way as configuration options in a ruff.toml file. As such, options specific to the Ruff linter need to be prefixed with lint.(--config "lint.dummy-variable-rgx = '__.*'" rather than simply--config "dummy-variable-rgx = '__.*'"), and options specific to the Ruff formatter need to be prefixed with format..

If a specific configuration option is simultaneously overridden by a dedicated flag and by the --config flag, the dedicated flag takes priority. In this example, the maximum permitted line length will be set to 90, not 100:

[](#%5F%5Fcodelineno-23-1)$ ruff format path/to/file --line-length=90 --config "line-length=100"

Specifying --config "line-length=90" will override the line-lengthsetting from all configuration files detected by Ruff, including configuration files discovered in subdirectories. In this respect, specifying --config "line-length=90" has the same effect as specifying --line-length=90, which will similarly override the line-length setting from all configuration files detected by Ruff, regardless of where a specific configuration file is located.

Full command-line interface

See ruff help for the full list of Ruff's top-level commands:

[](#%5F%5Fcodelineno-24-1)Ruff: An extremely fast Python linter and code formatter. [](#%5F%5Fcodelineno-24-2) [](#%5F%5Fcodelineno-24-3)Usage: ruff [OPTIONS] <COMMAND> [](#%5F%5Fcodelineno-24-4) [](#%5F%5Fcodelineno-24-5)Commands: [](#%5F%5Fcodelineno-24-6) check Run Ruff on the given files or directories [](#%5F%5Fcodelineno-24-7) rule Explain a rule (or all rules) [](#%5F%5Fcodelineno-24-8) config List or describe the available configuration options [](#%5F%5Fcodelineno-24-9) linter List all supported upstream linters [](#%5F%5Fcodelineno-24-10) clean Clear any caches in the current directory and any subdirectories [](#%5F%5Fcodelineno-24-11) format Run the Ruff formatter on the given files or directories [](#%5F%5Fcodelineno-24-12) server Run the language server [](#%5F%5Fcodelineno-24-13) analyze Run analysis over Python source code [](#%5F%5Fcodelineno-24-14) version Display Ruff's version [](#%5F%5Fcodelineno-24-15) help Print this message or the help of the given subcommand(s) [](#%5F%5Fcodelineno-24-16) [](#%5F%5Fcodelineno-24-17)Options: [](#%5F%5Fcodelineno-24-18) -h, --help Print help [](#%5F%5Fcodelineno-24-19) -V, --version Print version [](#%5F%5Fcodelineno-24-20) [](#%5F%5Fcodelineno-24-21)Log levels: [](#%5F%5Fcodelineno-24-22) -v, --verbose Enable verbose logging [](#%5F%5Fcodelineno-24-23) -q, --quiet Print diagnostics, but nothing else [](#%5F%5Fcodelineno-24-24) -s, --silent Disable all logging (but still exit with status code "1" upon [](#%5F%5Fcodelineno-24-25) detecting diagnostics) [](#%5F%5Fcodelineno-24-26) [](#%5F%5Fcodelineno-24-27)Global options: [](#%5F%5Fcodelineno-24-28) --config <CONFIG_OPTION> [](#%5F%5Fcodelineno-24-29) Either a path to a TOML configuration file (`pyproject.toml` or [](#%5F%5Fcodelineno-24-30) `ruff.toml`), or a TOML `<KEY> = <VALUE>` pair (such as you might [](#%5F%5Fcodelineno-24-31) find in a `ruff.toml` configuration file) overriding a specific [](#%5F%5Fcodelineno-24-32) configuration option. Overrides of individual settings using this [](#%5F%5Fcodelineno-24-33) option always take precedence over all configuration files, including [](#%5F%5Fcodelineno-24-34) configuration files that were also specified using `--config` [](#%5F%5Fcodelineno-24-35) --isolated [](#%5F%5Fcodelineno-24-36) Ignore all configuration files [](#%5F%5Fcodelineno-24-37) [](#%5F%5Fcodelineno-24-38)For help with a specific command, see: `ruff help <command>`.

Or ruff help check for more on the linting command:

[](#%5F%5Fcodelineno-25-1)Run Ruff on the given files or directories [](#%5F%5Fcodelineno-25-2) [](#%5F%5Fcodelineno-25-3)Usage: ruff check [OPTIONS] [FILES]... [](#%5F%5Fcodelineno-25-4) [](#%5F%5Fcodelineno-25-5)Arguments: [](#%5F%5Fcodelineno-25-6) [FILES]... List of files or directories to check [default: .] [](#%5F%5Fcodelineno-25-7) [](#%5F%5Fcodelineno-25-8)Options: [](#%5F%5Fcodelineno-25-9) --fix [](#%5F%5Fcodelineno-25-10) Apply fixes to resolve lint violations. Use `--no-fix` to disable or [](#%5F%5Fcodelineno-25-11) `--unsafe-fixes` to include unsafe fixes [](#%5F%5Fcodelineno-25-12) --unsafe-fixes [](#%5F%5Fcodelineno-25-13) Include fixes that may not retain the original intent of the code. [](#%5F%5Fcodelineno-25-14) Use `--no-unsafe-fixes` to disable [](#%5F%5Fcodelineno-25-15) --show-fixes [](#%5F%5Fcodelineno-25-16) Show an enumeration of all fixed lint violations. Use [](#%5F%5Fcodelineno-25-17) `--no-show-fixes` to disable [](#%5F%5Fcodelineno-25-18) --diff [](#%5F%5Fcodelineno-25-19) Avoid writing any fixed files back; instead, output a diff for each [](#%5F%5Fcodelineno-25-20) changed file to stdout, and exit 0 if there are no diffs. Implies [](#%5F%5Fcodelineno-25-21) `--fix-only` [](#%5F%5Fcodelineno-25-22) -w, --watch [](#%5F%5Fcodelineno-25-23) Run in watch mode by re-running whenever files change [](#%5F%5Fcodelineno-25-24) --fix-only [](#%5F%5Fcodelineno-25-25) Apply fixes to resolve lint violations, but don't report on, or exit [](#%5F%5Fcodelineno-25-26) non-zero for, leftover violations. Implies `--fix`. Use [](#%5F%5Fcodelineno-25-27) `--no-fix-only` to disable or `--unsafe-fixes` to include unsafe [](#%5F%5Fcodelineno-25-28) fixes [](#%5F%5Fcodelineno-25-29) --ignore-noqa [](#%5F%5Fcodelineno-25-30) Ignore any `# noqa` comments [](#%5F%5Fcodelineno-25-31) --output-format <OUTPUT_FORMAT> [](#%5F%5Fcodelineno-25-32) Output serialization format for violations. The default serialization [](#%5F%5Fcodelineno-25-33) format is "full" [env: RUFF_OUTPUT_FORMAT=] [possible values: [](#%5F%5Fcodelineno-25-34) concise, full, json, json-lines, junit, grouped, github, gitlab, [](#%5F%5Fcodelineno-25-35) pylint, rdjson, azure, sarif] [](#%5F%5Fcodelineno-25-36) -o, --output-file <OUTPUT_FILE> [](#%5F%5Fcodelineno-25-37) Specify file to write the linter output to (default: stdout) [env: [](#%5F%5Fcodelineno-25-38) RUFF_OUTPUT_FILE=] [](#%5F%5Fcodelineno-25-39) --target-version <TARGET_VERSION> [](#%5F%5Fcodelineno-25-40) The minimum Python version that should be supported [possible values: [](#%5F%5Fcodelineno-25-41) py37, py38, py39, py310, py311, py312, py313, py314] [](#%5F%5Fcodelineno-25-42) --preview [](#%5F%5Fcodelineno-25-43) Enable preview mode; checks will include unstable rules and fixes. [](#%5F%5Fcodelineno-25-44) Use `--no-preview` to disable [](#%5F%5Fcodelineno-25-45) --extension <EXTENSION> [](#%5F%5Fcodelineno-25-46) List of mappings from file extension to language (one of `python`, [](#%5F%5Fcodelineno-25-47) `ipynb`, `pyi`). For example, to treat `.ipy` files as IPython [](#%5F%5Fcodelineno-25-48) notebooks, use `--extension ipy:ipynb` [](#%5F%5Fcodelineno-25-49) --statistics [](#%5F%5Fcodelineno-25-50) Show counts for every rule with at least one violation [](#%5F%5Fcodelineno-25-51) --add-noqa [](#%5F%5Fcodelineno-25-52) Enable automatic additions of `noqa` directives to failing lines [](#%5F%5Fcodelineno-25-53) --show-files [](#%5F%5Fcodelineno-25-54) See the files Ruff will be run against with the current settings [](#%5F%5Fcodelineno-25-55) --show-settings [](#%5F%5Fcodelineno-25-56) See the settings Ruff will use to lint a given Python file [](#%5F%5Fcodelineno-25-57) -h, --help [](#%5F%5Fcodelineno-25-58) Print help [](#%5F%5Fcodelineno-25-59) [](#%5F%5Fcodelineno-25-60)Rule selection: [](#%5F%5Fcodelineno-25-61) --select <RULE_CODE> [](#%5F%5Fcodelineno-25-62) Comma-separated list of rule codes to enable (or ALL, to enable all [](#%5F%5Fcodelineno-25-63) rules) [](#%5F%5Fcodelineno-25-64) --ignore <RULE_CODE> [](#%5F%5Fcodelineno-25-65) Comma-separated list of rule codes to disable [](#%5F%5Fcodelineno-25-66) --extend-select <RULE_CODE> [](#%5F%5Fcodelineno-25-67) Like --select, but adds additional rule codes on top of those already [](#%5F%5Fcodelineno-25-68) specified [](#%5F%5Fcodelineno-25-69) --per-file-ignores <PER_FILE_IGNORES> [](#%5F%5Fcodelineno-25-70) List of mappings from file pattern to code to exclude [](#%5F%5Fcodelineno-25-71) --extend-per-file-ignores <EXTEND_PER_FILE_IGNORES> [](#%5F%5Fcodelineno-25-72) Like `--per-file-ignores`, but adds additional ignores on top of [](#%5F%5Fcodelineno-25-73) those already specified [](#%5F%5Fcodelineno-25-74) --fixable <RULE_CODE> [](#%5F%5Fcodelineno-25-75) List of rule codes to treat as eligible for fix. Only applicable when [](#%5F%5Fcodelineno-25-76) fix itself is enabled (e.g., via `--fix`) [](#%5F%5Fcodelineno-25-77) --unfixable <RULE_CODE> [](#%5F%5Fcodelineno-25-78) List of rule codes to treat as ineligible for fix. Only applicable [](#%5F%5Fcodelineno-25-79) when fix itself is enabled (e.g., via `--fix`) [](#%5F%5Fcodelineno-25-80) --extend-fixable <RULE_CODE> [](#%5F%5Fcodelineno-25-81) Like --fixable, but adds additional rule codes on top of those [](#%5F%5Fcodelineno-25-82) already specified [](#%5F%5Fcodelineno-25-83) [](#%5F%5Fcodelineno-25-84)File selection: [](#%5F%5Fcodelineno-25-85) --exclude <FILE_PATTERN> [](#%5F%5Fcodelineno-25-86) List of paths, used to omit files and/or directories from analysis [](#%5F%5Fcodelineno-25-87) --extend-exclude <FILE_PATTERN> [](#%5F%5Fcodelineno-25-88) Like --exclude, but adds additional files and directories on top of [](#%5F%5Fcodelineno-25-89) those already excluded [](#%5F%5Fcodelineno-25-90) --respect-gitignore [](#%5F%5Fcodelineno-25-91) Respect file exclusions via `.gitignore` and other standard ignore [](#%5F%5Fcodelineno-25-92) files. Use `--no-respect-gitignore` to disable [](#%5F%5Fcodelineno-25-93) --force-exclude [](#%5F%5Fcodelineno-25-94) Enforce exclusions, even for paths passed to Ruff directly on the [](#%5F%5Fcodelineno-25-95) command-line. Use `--no-force-exclude` to disable [](#%5F%5Fcodelineno-25-96) [](#%5F%5Fcodelineno-25-97)Miscellaneous: [](#%5F%5Fcodelineno-25-98) -n, --no-cache [](#%5F%5Fcodelineno-25-99) Disable cache reads [env: RUFF_NO_CACHE=] [](#%5F%5Fcodelineno-25-100) --cache-dir <CACHE_DIR> [](#%5F%5Fcodelineno-25-101) Path to the cache directory [env: RUFF_CACHE_DIR=] [](#%5F%5Fcodelineno-25-102) --stdin-filename <STDIN_FILENAME> [](#%5F%5Fcodelineno-25-103) The name of the file when passing it through stdin [](#%5F%5Fcodelineno-25-104) -e, --exit-zero [](#%5F%5Fcodelineno-25-105) Exit with status code "0", even upon detecting lint violations [](#%5F%5Fcodelineno-25-106) --exit-non-zero-on-fix [](#%5F%5Fcodelineno-25-107) Exit with a non-zero status code if any files were modified via fix, [](#%5F%5Fcodelineno-25-108) even if no lint violations remain [](#%5F%5Fcodelineno-25-109) [](#%5F%5Fcodelineno-25-110)Log levels: [](#%5F%5Fcodelineno-25-111) -v, --verbose Enable verbose logging [](#%5F%5Fcodelineno-25-112) -q, --quiet Print diagnostics, but nothing else [](#%5F%5Fcodelineno-25-113) -s, --silent Disable all logging (but still exit with status code "1" upon [](#%5F%5Fcodelineno-25-114) detecting diagnostics) [](#%5F%5Fcodelineno-25-115) [](#%5F%5Fcodelineno-25-116)Global options: [](#%5F%5Fcodelineno-25-117) --config <CONFIG_OPTION> [](#%5F%5Fcodelineno-25-118) Either a path to a TOML configuration file (`pyproject.toml` or [](#%5F%5Fcodelineno-25-119) `ruff.toml`), or a TOML `<KEY> = <VALUE>` pair (such as you might [](#%5F%5Fcodelineno-25-120) find in a `ruff.toml` configuration file) overriding a specific [](#%5F%5Fcodelineno-25-121) configuration option. Overrides of individual settings using this [](#%5F%5Fcodelineno-25-122) option always take precedence over all configuration files, including [](#%5F%5Fcodelineno-25-123) configuration files that were also specified using `--config` [](#%5F%5Fcodelineno-25-124) --isolated [](#%5F%5Fcodelineno-25-125) Ignore all configuration files

Or ruff help format for more on the formatting command:

[](#%5F%5Fcodelineno-26-1)Run the Ruff formatter on the given files or directories [](#%5F%5Fcodelineno-26-2) [](#%5F%5Fcodelineno-26-3)Usage: ruff format [OPTIONS] [FILES]... [](#%5F%5Fcodelineno-26-4) [](#%5F%5Fcodelineno-26-5)Arguments: [](#%5F%5Fcodelineno-26-6) [FILES]... List of files or directories to format [default: .] [](#%5F%5Fcodelineno-26-7) [](#%5F%5Fcodelineno-26-8)Options: [](#%5F%5Fcodelineno-26-9) --check [](#%5F%5Fcodelineno-26-10) Avoid writing any formatted files back; instead, exit with a non-zero [](#%5F%5Fcodelineno-26-11) status code if any files would have been modified, and zero otherwise [](#%5F%5Fcodelineno-26-12) --diff [](#%5F%5Fcodelineno-26-13) Avoid writing any formatted files back; instead, exit with a non-zero [](#%5F%5Fcodelineno-26-14) status code and the difference between the current file and how the [](#%5F%5Fcodelineno-26-15) formatted file would look like [](#%5F%5Fcodelineno-26-16) --extension <EXTENSION> [](#%5F%5Fcodelineno-26-17) List of mappings from file extension to language (one of `python`, [](#%5F%5Fcodelineno-26-18) `ipynb`, `pyi`). For example, to treat `.ipy` files as IPython [](#%5F%5Fcodelineno-26-19) notebooks, use `--extension ipy:ipynb` [](#%5F%5Fcodelineno-26-20) --target-version <TARGET_VERSION> [](#%5F%5Fcodelineno-26-21) The minimum Python version that should be supported [possible values: [](#%5F%5Fcodelineno-26-22) py37, py38, py39, py310, py311, py312, py313, py314] [](#%5F%5Fcodelineno-26-23) --preview [](#%5F%5Fcodelineno-26-24) Enable preview mode; enables unstable formatting. Use `--no-preview` [](#%5F%5Fcodelineno-26-25) to disable [](#%5F%5Fcodelineno-26-26) -h, --help [](#%5F%5Fcodelineno-26-27) Print help (see more with '--help') [](#%5F%5Fcodelineno-26-28) [](#%5F%5Fcodelineno-26-29)Miscellaneous: [](#%5F%5Fcodelineno-26-30) -n, --no-cache [](#%5F%5Fcodelineno-26-31) Disable cache reads [env: RUFF_NO_CACHE=] [](#%5F%5Fcodelineno-26-32) --cache-dir <CACHE_DIR> [](#%5F%5Fcodelineno-26-33) Path to the cache directory [env: RUFF_CACHE_DIR=] [](#%5F%5Fcodelineno-26-34) --stdin-filename <STDIN_FILENAME> [](#%5F%5Fcodelineno-26-35) The name of the file when passing it through stdin [](#%5F%5Fcodelineno-26-36) --exit-non-zero-on-format [](#%5F%5Fcodelineno-26-37) Exit with a non-zero status code if any files were modified via [](#%5F%5Fcodelineno-26-38) format, even if all files were formatted successfully [](#%5F%5Fcodelineno-26-39) [](#%5F%5Fcodelineno-26-40)File selection: [](#%5F%5Fcodelineno-26-41) --respect-gitignore [](#%5F%5Fcodelineno-26-42) Respect file exclusions via `.gitignore` and other standard ignore [](#%5F%5Fcodelineno-26-43) files. Use `--no-respect-gitignore` to disable [](#%5F%5Fcodelineno-26-44) --exclude <FILE_PATTERN> [](#%5F%5Fcodelineno-26-45) List of paths, used to omit files and/or directories from analysis [](#%5F%5Fcodelineno-26-46) --force-exclude [](#%5F%5Fcodelineno-26-47) Enforce exclusions, even for paths passed to Ruff directly on the [](#%5F%5Fcodelineno-26-48) command-line. Use `--no-force-exclude` to disable [](#%5F%5Fcodelineno-26-49) [](#%5F%5Fcodelineno-26-50)Format configuration: [](#%5F%5Fcodelineno-26-51) --line-length <LINE_LENGTH> Set the line-length [](#%5F%5Fcodelineno-26-52) [](#%5F%5Fcodelineno-26-53)Editor options: [](#%5F%5Fcodelineno-26-54) --range <RANGE> When specified, Ruff will try to only format the code in [](#%5F%5Fcodelineno-26-55) the given range. [](#%5F%5Fcodelineno-26-56) It might be necessary to extend the start backwards or [](#%5F%5Fcodelineno-26-57) the end forwards, to fully enclose a logical line. [](#%5F%5Fcodelineno-26-58) The `<RANGE>` uses the format [](#%5F%5Fcodelineno-26-59) `<start_line>:<start_column>-<end_line>:<end_column>`. [](#%5F%5Fcodelineno-26-60) [](#%5F%5Fcodelineno-26-61)Log levels: [](#%5F%5Fcodelineno-26-62) -v, --verbose Enable verbose logging [](#%5F%5Fcodelineno-26-63) -q, --quiet Print diagnostics, but nothing else [](#%5F%5Fcodelineno-26-64) -s, --silent Disable all logging (but still exit with status code "1" upon [](#%5F%5Fcodelineno-26-65) detecting diagnostics) [](#%5F%5Fcodelineno-26-66) [](#%5F%5Fcodelineno-26-67)Global options: [](#%5F%5Fcodelineno-26-68) --config <CONFIG_OPTION> [](#%5F%5Fcodelineno-26-69) Either a path to a TOML configuration file (`pyproject.toml` or [](#%5F%5Fcodelineno-26-70) `ruff.toml`), or a TOML `<KEY> = <VALUE>` pair (such as you might [](#%5F%5Fcodelineno-26-71) find in a `ruff.toml` configuration file) overriding a specific [](#%5F%5Fcodelineno-26-72) configuration option. Overrides of individual settings using this [](#%5F%5Fcodelineno-26-73) option always take precedence over all configuration files, including [](#%5F%5Fcodelineno-26-74) configuration files that were also specified using `--config` [](#%5F%5Fcodelineno-26-75) --isolated [](#%5F%5Fcodelineno-26-76) Ignore all configuration files

Shell autocompletion

Ruff supports autocompletion for most shells. A shell-specific completion script can be generated by ruff generate-shell-completion <SHELL>, where <SHELL> is one of bash, elvish, fig, fish,powershell, or zsh.

The exact steps required to enable autocompletion will vary by shell. For example instructions, see the Poetry orripgrep documentation.

As an example: to enable autocompletion for Zsh, runruff generate-shell-completion zsh > ~/.zfunc/_ruff. Then add the following line to your~/.zshrc file, if they're not already present:

[](#%5F%5Fcodelineno-27-1)fpath+=~/.zfunc [](#%5F%5Fcodelineno-27-2)autoload -Uz compinit && compinit