配置 Ruff
Ruff 可以通过 pyproject.toml、ruff.toml 或 .ruff.toml 文件进行配置。
无论您是将 Ruff 用作 linter、formatter 还是两者都用，底层配置策略和语义都是相同的。
有关可用配置选项的完整枚举，请参阅 设置。
如果未指定，Ruff 的默认配置等效于
[tool.ruff]
# Exclude a variety of commonly ignored directories.
exclude = [
".bzr",
".direnv",
".eggs",
".git",
".git-rewrite",
".hg",
".ipynb_checkpoints",
".mypy_cache",
".nox",
".pants.d",
".pyenv",
".pytest_cache",
".pytype",
".ruff_cache",
".svn",
".tox",
".venv",
".vscode",
"__pypackages__",
"_build",
"buck-out",
"build",
"dist",
"node_modules",
"site-packages",
"venv",
]
# Same as Black.
line-length = 88
indent-width = 4
# Assume Python 3.9
target-version = "py39"
[tool.ruff.lint]
# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`) codes by default.
# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
# McCabe complexity (`C901`) by default.
select = ["E4", "E7", "E9", "F"]
ignore = []
# Allow fix for all enabled rules (when `--fix`) is provided.
fixable = ["ALL"]
unfixable = []
# Allow unused variables when underscore-prefixed.
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
[tool.ruff.format]
# Like Black, use double quotes for strings.
quote-style = "double"
# Like Black, indent with spaces, rather than tabs.
indent-style = "space"
# Like Black, respect magic trailing commas.
skip-magic-trailing-comma = false
# Like Black, automatically detect the appropriate line ending.
line-ending = "auto"
# Enable auto-formatting of code examples in docstrings. Markdown,
# reStructuredText code/literal blocks and doctests are all supported.
#
# This is currently disabled by default, but it is planned for this
# to be opt-out in the future.
docstring-code-format = false
# Set the line length limit used when formatting code snippets in
# docstrings.
#
# This only has an effect when the `docstring-code-format` setting is
# enabled.
docstring-code-line-length = "dynamic"
# Exclude a variety of commonly ignored directories.
exclude = [
".bzr",
".direnv",
".eggs",
".git",
".git-rewrite",
".hg",
".ipynb_checkpoints",
".mypy_cache",
".nox",
".pants.d",
".pyenv",
".pytest_cache",
".pytype",
".ruff_cache",
".svn",
".tox",
".venv",
".vscode",
"__pypackages__",
"_build",
"buck-out",
"build",
"dist",
"node_modules",
"site-packages",
"venv",
]
# Same as Black.
line-length = 88
indent-width = 4
# Assume Python 3.9
target-version = "py39"
[lint]
# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`) codes by default.
# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
# McCabe complexity (`C901`) by default.
select = ["E4", "E7", "E9", "F"]
ignore = []
# Allow fix for all enabled rules (when `--fix`) is provided.
fixable = ["ALL"]
unfixable = []
# Allow unused variables when underscore-prefixed.
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
[format]
# Like Black, use double quotes for strings.
quote-style = "double"
# Like Black, indent with spaces, rather than tabs.
indent-style = "space"
# Like Black, respect magic trailing commas.
skip-magic-trailing-comma = false
# Like Black, automatically detect the appropriate line ending.
line-ending = "auto"
# Enable auto-formatting of code examples in docstrings. Markdown,
# reStructuredText code/literal blocks and doctests are all supported.
#
# This is currently disabled by default, but it is planned for this
# to be opt-out in the future.
docstring-code-format = false
# Set the line length limit used when formatting code snippets in
# docstrings.
#
# This only has an effect when the `docstring-code-format` setting is
# enabled.
docstring-code-line-length = "dynamic"
例如，以下配置将 Ruff 配置为
[tool.ruff.lint]
# 1. Enable flake8-bugbear (`B`) rules, in addition to the defaults.
select = ["E4", "E7", "E9", "F", "B"]
# 2. Avoid enforcing line-length violations (`E501`)
ignore = ["E501"]
# 3. Avoid trying to fix flake8-bugbear (`B`) violations.
unfixable = ["B"]
# 4. Ignore `E402` (import violations) in all `__init__.py` files, and in selected subdirectories.
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["E402"]
"**/{tests,docs,tools}/*" = ["E402"]
[tool.ruff.format]
# 5. Use single quotes in `ruff format`.
quote-style = "single"
[lint]
# 1. Enable flake8-bugbear (`B`) rules, in addition to the defaults.
select = ["E4", "E7", "E9", "F", "B"]
# 2. Avoid enforcing line-length violations (`E501`)
ignore = ["E501"]
# 3. Avoid trying to fix flake8-bugbear (`B`) violations.
unfixable = ["B"]
# 4. Ignore `E402` (import violations) in all `__init__.py` files, and in selected subdirectories.
[lint.per-file-ignores]
"__init__.py" = ["E402"]
"**/{tests,docs,tools}/*" = ["E402"]
[format]
# 5. Use single quotes in `ruff format`.
quote-style = "single"
Linter 插件配置表示为子部分，例如
Ruff 遵循 pyproject.toml、ruff.toml 和 .ruff.toml 文件。所有三个都实现了等效的模式（尽管在 ruff.toml 和 .ruff.toml 版本中，省略了 [tool.ruff] 标头和 tool.ruff 部分前缀）。
有关可用配置选项的完整枚举，请参阅 设置。
配置文件发现
与 ESLint 类似，Ruff 支持分层配置，使得目录层次结构中“最近”的配置文件用于每个单独的文件，配置文件中的所有路径（例如，exclude globs，src 路径）都相对于包含该配置文件的目录进行解析。
这些规则有一些例外情况
- 在查找给定路径的“最近”
pyproject.toml文件时，Ruff 会忽略任何缺少[tool.ruff]部分的pyproject.toml文件。 - 如果通过
--config直接传递配置文件，则这些设置将用于所有分析的文件，并且该配置文件中的任何相对路径（如excludeglobs 或src路径）都相对于当前工作目录进行解析。 - 如果在文件系统层次结构中未找到配置文件，Ruff 将回退到使用默认配置。如果在
${config_dir}/ruff/pyproject.toml处存在用户特定的配置文件，则将使用该文件而不是默认配置，其中${config_dir}通过etcetera的本机策略确定，并且所有相对路径再次相对于当前工作目录解析。 - 在命令行上提供的任何配置文件支持的设置（例如，通过
--select）将覆盖每个已解析配置文件中的设置。
与 ESLint 不同，Ruff 不会跨配置文件合并设置；相反，使用“最近”的配置文件，并且忽略任何父配置文件。为了代替这种隐式级联，Ruff 支持 extend 字段，允许您从另一个配置文件继承设置，如下所示
以上所有规则同样适用于 pyproject.toml、ruff.toml 和 .ruff.toml 文件。如果 Ruff 在同一目录中检测到多个配置文件，则 .ruff.toml 文件将优先于 ruff.toml 文件，而 ruff.toml 文件将优先于 pyproject.toml 文件。
推断 Python 版本
当没有发现的配置指定 target-version 时，Ruff 将尝试回退到与附近 pyproject.toml 中的 requires-python 字段兼容的最低版本。 此行为的规则如下
- 如果直接传递配置文件，Ruff 不会尝试推断缺少的
target-version。 - 如果在文件系统层次结构中找到配置文件，Ruff 将从与找到的配置位于同一目录中的
pyproject.toml文件中的requires-python字段推断缺少的target-version。 - 如果我们使用来自
${config_dir}/ruff/pyproject.toml的用户级别配置，则在当前工作目录的祖先中找到的第一个pyproject.toml文件中的requires-python字段优先于用户级别配置中的target-version。 - 如果未找到配置文件，Ruff 将从当前工作目录的祖先中找到的第一个
pyproject.toml文件中的requires-python字段推断target-version。
请注意，在最后两种情况下，Ruff 的行为可能会因调用它的工作目录而异。
Python 文件发现
当在命令行上传递路径时，Ruff 将自动发现该路径中的所有 Python 文件，同时考虑到每个目录的配置文件中的 exclude 和 extend-exclude 设置。
也可以通过将 exclude 设置限定为工具特定的配置表来有选择地从 linting 或格式化中排除文件。 例如，以下配置将阻止 ruff 格式化 .pyi 文件，但会继续将其包含在 linting 中
默认情况下，Ruff 还会跳过通过 .ignore、.gitignore、.git/info/exclude 和全局 gitignore 文件省略的任何文件（请参阅：respect-gitignore）。
传递给 ruff 的文件始终会被分析，而不管上述标准如何。 例如，ruff check /path/to/excluded/file.py 将始终 lint file.py。
默认包含
默认情况下，Ruff 将发现匹配 *.py、*.pyi、*.ipynb 或 pyproject.toml 的文件。
要 lint 或格式化具有其他文件扩展名的文件，请使用 extend-include 设置。 您还可以使用 include 设置更改默认选择。
警告
提供给 include 的路径必须匹配文件。 例如，include = ["src"] 将失败，因为它匹配一个目录。
Jupyter Notebook 发现
Ruff 内置支持 linting 和格式化 Jupyter Notebooks，默认情况下在 0.6.0 及更高版本上进行 linting 和格式化。
如果您更喜欢仅 lint 或仅格式化 Jupyter Notebook 文件，您可以使用特定于部分的 exclude 选项来执行此操作。 例如，以下配置将仅 lint Jupyter Notebook 文件而不格式化它们
相反，以下配置将仅格式化 Jupyter Notebook 文件而不 lint 它们
您可以通过更新 extend-exclude 设置来完全禁用 Jupyter Notebook 支持
如果您想忽略专门针对 Jupyter Notebook 文件的某些规则，您可以使用 per-file-ignores 设置来执行此操作
某些规则在应用于 Jupyter Notebook 文件时具有不同的行为。 例如，当应用于 .py 文件时，module-import-not-at-top-of-file (E402) 规则检测文件顶部的导入，但对于笔记本，它检测单元格顶部的导入。 对于给定的规则，该规则的文档将始终指定它在应用于 Jupyter Notebook 文件时是否具有不同的行为。
命令行界面
一些配置选项可以通过命令行上的专用标志提供或覆盖。 这包括与规则启用和禁用、文件发现、日志级别等相关的选项
所有其他配置选项都可以使用 --config 标志通过命令行设置，如下所述。
--config 命令行标志
--config 标志有两种用途。 最常用于指向您希望 Ruff 使用的配置文件，例如
但是，--config 标志也可以用于使用 TOML <KEY> = <VALUE> 对提供配置设置的任意覆盖。 这在您希望覆盖没有专用命令行标志的配置设置的情况下最有用。
在下面的示例中，--config 标志是从命令行覆盖 dummy-variable-rgx 配置设置的唯一方法，因为此设置没有专用的 CLI 标志。 per-file-ignores 设置也可以通过 --per-file-ignores 专用标志覆盖，但使用 --config 覆盖该设置也可以
$ ruff check path/to/file --config path/to/ruff.toml --config "lint.dummy-variable-rgx = '__.*'" --config "lint.per-file-ignores = {'some_file.py' = ['F841']}"
传递给 --config 的配置选项的解析方式与 ruff.toml 文件中的配置选项相同。 因此，特定于 Ruff linter 的选项需要以 lint. 为前缀（--config "lint.dummy-variable-rgx = '__.*'" 而不是简单的 --config "dummy-variable-rgx = '__.*'"），而特定于 Ruff 格式化程序的选项需要以 format. 为前缀。
如果特定配置选项同时被专用标志和 --config 标志覆盖，则专用标志优先。 在此示例中，允许的最大行长度将设置为 90，而不是 100
指定 --config "line-length=90" 将覆盖 Ruff 检测到的所有配置文件中的 line-length 设置，包括在子目录中发现的配置文件。 在这方面，指定 --config "line-length=90" 的效果与指定 --line-length=90 相同，后者同样会覆盖 Ruff 检测到的所有配置文件中的 line-length 设置，而不管特定配置文件位于何处。
完整命令行界面
有关 Ruff 顶级命令的完整列表，请参阅 ruff help
Ruff: An extremely fast Python linter and code formatter.
Usage: ruff [OPTIONS] <COMMAND>
Commands:
check Run Ruff on the given files or directories
rule Explain a rule (or all rules)
config List or describe the available configuration options
linter List all supported upstream linters
clean Clear any caches in the current directory and any subdirectories
format Run the Ruff formatter on the given files or directories
server Run the language server
analyze Run analysis over Python source code
version Display Ruff's version
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
Log levels:
-v, --verbose Enable verbose logging
-q, --quiet Print diagnostics, but nothing else
-s, --silent Disable all logging (but still exit with status code "1" upon
detecting diagnostics)
Global options:
--config <CONFIG_OPTION>
Either a path to a TOML configuration file (`pyproject.toml` or
`ruff.toml`), or a TOML `<KEY> = <VALUE>` pair (such as you might
find in a `ruff.toml` configuration file) overriding a specific
configuration option. Overrides of individual settings using this
option always take precedence over all configuration files, including
configuration files that were also specified using `--config`
--isolated
Ignore all configuration files
For help with a specific command, see: `ruff help <command>`.
或 ruff help check 以获取有关 linting 命令的更多信息
Run Ruff on the given files or directories
Usage: ruff check [OPTIONS] [FILES]...
Arguments:
[FILES]... List of files or directories to check [default: .]
Options:
--fix
Apply fixes to resolve lint violations. Use `--no-fix` to disable or
`--unsafe-fixes` to include unsafe fixes
--unsafe-fixes
Include fixes that may not retain the original intent of the code.
Use `--no-unsafe-fixes` to disable
--show-fixes
Show an enumeration of all fixed lint violations. Use
`--no-show-fixes` to disable
--diff
Avoid writing any fixed files back; instead, output a diff for each
changed file to stdout, and exit 0 if there are no diffs. Implies
`--fix-only`
-w, --watch
Run in watch mode by re-running whenever files change
--fix-only
Apply fixes to resolve lint violations, but don't report on, or exit
non-zero for, leftover violations. Implies `--fix`. Use
`--no-fix-only` to disable or `--unsafe-fixes` to include unsafe
fixes
--ignore-noqa
Ignore any `# noqa` comments
--output-format <OUTPUT_FORMAT>
Output serialization format for violations. The default serialization
format is "full" [env: RUFF_OUTPUT_FORMAT=] [possible values:
concise, full, json, json-lines, junit, grouped, github, gitlab,
pylint, rdjson, azure, sarif]
-o, --output-file <OUTPUT_FILE>
Specify file to write the linter output to (default: stdout) [env:
RUFF_OUTPUT_FILE=]
--target-version <TARGET_VERSION>
The minimum Python version that should be supported [possible values:
py37, py38, py39, py310, py311, py312, py313, py314]
--preview
Enable preview mode; checks will include unstable rules and fixes.
Use `--no-preview` to disable
--extension <EXTENSION>
List of mappings from file extension to language (one of `python`,
`ipynb`, `pyi`). For example, to treat `.ipy` files as IPython
notebooks, use `--extension ipy:ipynb`
--statistics
Show counts for every rule with at least one violation
--add-noqa
Enable automatic additions of `noqa` directives to failing lines
--show-files
See the files Ruff will be run against with the current settings
--show-settings
See the settings Ruff will use to lint a given Python file
-h, --help
Print help
Rule selection:
--select <RULE_CODE>
Comma-separated list of rule codes to enable (or ALL, to enable all
rules)
--ignore <RULE_CODE>
Comma-separated list of rule codes to disable
--extend-select <RULE_CODE>
Like --select, but adds additional rule codes on top of those already
specified
--per-file-ignores <PER_FILE_IGNORES>
List of mappings from file pattern to code to exclude
--extend-per-file-ignores <EXTEND_PER_FILE_IGNORES>
Like `--per-file-ignores`, but adds additional ignores on top of
those already specified
--fixable <RULE_CODE>
List of rule codes to treat as eligible for fix. Only applicable when
fix itself is enabled (e.g., via `--fix`)
--unfixable <RULE_CODE>
List of rule codes to treat as ineligible for fix. Only applicable
when fix itself is enabled (e.g., via `--fix`)
--extend-fixable <RULE_CODE>
Like --fixable, but adds additional rule codes on top of those
already specified
File selection:
--exclude <FILE_PATTERN>
List of paths, used to omit files and/or directories from analysis
--extend-exclude <FILE_PATTERN>
Like --exclude, but adds additional files and directories on top of
those already excluded
--respect-gitignore
Respect file exclusions via `.gitignore` and other standard ignore
files. Use `--no-respect-gitignore` to disable
--force-exclude
Enforce exclusions, even for paths passed to Ruff directly on the
command-line. Use `--no-force-exclude` to disable
Miscellaneous:
-n, --no-cache
Disable cache reads [env: RUFF_NO_CACHE=]
--cache-dir <CACHE_DIR>
Path to the cache directory [env: RUFF_CACHE_DIR=]
--stdin-filename <STDIN_FILENAME>
The name of the file when passing it through stdin
-e, --exit-zero
Exit with status code "0", even upon detecting lint violations
--exit-non-zero-on-fix
Exit with a non-zero status code if any files were modified via fix,
even if no lint violations remain
Log levels:
-v, --verbose Enable verbose logging
-q, --quiet Print diagnostics, but nothing else
-s, --silent Disable all logging (but still exit with status code "1" upon
detecting diagnostics)
Global options:
--config <CONFIG_OPTION>
Either a path to a TOML configuration file (`pyproject.toml` or
`ruff.toml`), or a TOML `<KEY> = <VALUE>` pair (such as you might
find in a `ruff.toml` configuration file) overriding a specific
configuration option. Overrides of individual settings using this
option always take precedence over all configuration files, including
configuration files that were also specified using `--config`
--isolated
Ignore all configuration files
或 ruff help format 以获取有关格式化命令的更多信息
Run the Ruff formatter on the given files or directories
Usage: ruff format [OPTIONS] [FILES]...
Arguments:
[FILES]... List of files or directories to format [default: .]
Options:
--check
Avoid writing any formatted files back; instead, exit with a non-zero
status code if any files would have been modified, and zero otherwise
--diff
Avoid writing any formatted files back; instead, exit with a non-zero
status code and the difference between the current file and how the
formatted file would look like
--extension <EXTENSION>
List of mappings from file extension to language (one of `python`,
`ipynb`, `pyi`). For example, to treat `.ipy` files as IPython
notebooks, use `--extension ipy:ipynb`
--target-version <TARGET_VERSION>
The minimum Python version that should be supported [possible values:
py37, py38, py39, py310, py311, py312, py313, py314]
--preview
Enable preview mode; enables unstable formatting. Use `--no-preview`
to disable
-h, --help
Print help (see more with '--help')
Miscellaneous:
-n, --no-cache
Disable cache reads [env: RUFF_NO_CACHE=]
--cache-dir <CACHE_DIR>
Path to the cache directory [env: RUFF_CACHE_DIR=]
--stdin-filename <STDIN_FILENAME>
The name of the file when passing it through stdin
--exit-non-zero-on-format
Exit with a non-zero status code if any files were modified via
format, even if all files were formatted successfully
File selection:
--respect-gitignore
Respect file exclusions via `.gitignore` and other standard ignore
files. Use `--no-respect-gitignore` to disable
--exclude <FILE_PATTERN>
List of paths, used to omit files and/or directories from analysis
--force-exclude
Enforce exclusions, even for paths passed to Ruff directly on the
command-line. Use `--no-force-exclude` to disable
Format configuration:
--line-length <LINE_LENGTH> Set the line-length
Editor options:
--range <RANGE> When specified, Ruff will try to only format the code in
the given range.
It might be necessary to extend the start backwards or
the end forwards, to fully enclose a logical line.
The `<RANGE>` uses the format
`<start_line>:<start_column>-<end_line>:<end_column>`.
Log levels:
-v, --verbose Enable verbose logging
-q, --quiet Print diagnostics, but nothing else
-s, --silent Disable all logging (but still exit with status code "1" upon
detecting diagnostics)
Global options:
--config <CONFIG_OPTION>
Either a path to a TOML configuration file (`pyproject.toml` or
`ruff.toml`), or a TOML `<KEY> = <VALUE>` pair (such as you might
find in a `ruff.toml` configuration file) overriding a specific
configuration option. Overrides of individual settings using this
option always take precedence over all configuration files, including
configuration files that were also specified using `--config`
--isolated
Ignore all configuration files
Shell 自动补全
Ruff 支持大多数 shell 的自动补全。 可以通过 ruff generate-shell-completion <SHELL> 生成 shell 特定的完成脚本，其中 <SHELL> 是 bash、elvish、fig、fish、powershell 或 zsh 之一。
启用自动补全所需的确切步骤因 shell 而异。 有关示例说明，请参阅 Poetry 或 ripgrep 文档。
例如：要为 Zsh 启用自动补全，请运行 ruff generate-shell-completion zsh > ~/.zfunc/_ruff。 然后将以下行添加到您的 ~/.zshrc 文件中，如果它们尚未存在