Visual Studio Code的Ruff扩展

[!注意]

从Ruff v0.4.5开始，Ruff附带了一个用Rust编写的内置语言服务器：⚡ ruff server ⚡

该服务器在Ruff v0.5.3中被标记为稳定版，如果可用，扩展将自动使用它。

参见：启用基于Rust的语言服务器。

这是一个适用于Ruff的Visual Studio Code扩展，Ruff是一个用Rust编写的极速Python代码检查器和格式化工具。该扩展可在Visual Studio Marketplace上获取。

Ruff可以用来替代Flake8（以及数十个插件）、Black、isort、pyupgrade等工具，同时执行速度比任何单个工具都要快数十倍或数百倍。

该扩展附带ruff==0.5.7。

亮点

可自动修复的违规项的"快速修复"操作（如未使用的导入）

"修复所有"：自动修复所有可自动修复的违规项

"格式化文档"：与Black兼容的代码格式化

"整理导入"：与isort兼容的导入排序

使用方法

安装在Visual Studio Code中后，当你打开或编辑Python或Jupyter Notebook文件时，ruff将自动执行。

如果你想禁用Ruff，可以在Visual Studio Code中禁用此扩展。

修复安全性

Ruff的自动修复被标记为"安全"和"不安全"。默认情况下，"修复所有"操作不会应用不安全的修复。但是，可以使用"快速修复"操作手动应用不安全的修复。可以通过在Ruff配置文件中设置unsafe-fixes = true或在"Lint args"设置中添加--unsafe-fixes标志来启用使用"修复所有"时应用不安全的修复。

有关修复安全性如何工作的更多详情，请参阅Ruff修复文档。

Jupyter Notebook支持

该扩展通过语言服务器协议3.17版本中添加的Notebook文档同步功能支持Jupyter Notebooks。这已在ruff-lsp的v0.0.43版本中实现，为Jupyter Notebooks提供了与Python文件相同的全部现有功能，包括诊断、代码操作和格式化。

这需要Ruff版本v0.1.3或更高版本。

原生服务器

原生服务器原生支持Jupyter Notebooks。与ruff-lsp不同，原生服务器要求用户明确将Jupyter Notebooks包含在要检查和格式化的文件集中。这可以通过更新Ruff配置文件中的extend-include设置来完成。

[tool.ruff]
extend-include = ["*.ipynb"]

更多信息请参阅Ruff文档中的Jupyter Notebook发现部分。

不受信任的工作区

v2024.32.0新功能

该扩展支持在不受信任的工作区中加载。当工作区不受信任时，即使nativeServer设置为off，扩展也将始终使用基于Rust的语言服务器。这是因为基于Python的语言服务器需要Python解释器才能运行，而这在不受信任的工作区中是不允许的。这也意味着扩展将始终使用ruff二进制文件的捆绑可执行文件，而不考虑任何其他设置。

以下设置在不受信任的工作区中不受支持：

• ruff.configuration
• ruff.importStrategy
• ruff.interpreter
• ruff.path

设置

有关扩展中可用的完整设置列表，请参阅Ruff语言服务器文档。

配置VS Code

你可以通过在settings.json中启用editor.formatOnSave操作并将Ruff设置为默认格式化工具来配置Ruff在保存时格式化Python代码：

{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

对于Jupyter Notebooks：

{
  "notebook.formatOnSave.enabled": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

你可以通过在settings.json中启用source.fixAll操作来配置Ruff在保存时修复lint违规：

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    }
  }
}

对于Jupyter Notebooks：

{
  "notebook.codeActionsOnSave": {
    "notebook.source.fixAll": "explicit"
  }
}

同样，你可以通过在settings.json中启用source.organizeImports操作来配置Ruff在保存时整理导入：

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  }
}

对于Jupyter Notebooks：

{
  "notebook.codeActionsOnSave": {
    "notebook.source.organizeImports": "explicit"
  }
}

综合起来，你可以通过以下settings.json配置Ruff在保存时格式化、修复和整理导入：

{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

对于Jupyter Notebooks：

{
  "notebook.formatOnSave.enabled": true,
  "notebook.codeActionsOnSave": {
    "notebook.source.fixAll": "explicit",
    "notebook.source.organizeImports": "explicit"
  },
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

注意：如果你在VS Code中使用Ruff整理导入，并且还期望从命令行运行Ruff，你需要通过在extend-select中添加"I"来启用Ruff的isort规则。

注意：上述Notebook配置将对每个单元格单独运行操作。这是VS Code处理Notebook操作的方式，与ruff-lsp无关。如果你更喜欢一次性对整个notebook运行操作，请使用带有Ruff前缀的命令，如Ruff: Organize Imports和Ruff: Fix all auto-fixable problems。

如果你使用VS Code Python扩展，可以配置VS Code在保存时使用Ruff修复违规，然后使用Black扩展重新格式化，通过以下settings.json实现：

{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    },
    "editor.defaultFormatter": "ms-python.black-formatter"
  }
}

如果你想使用Ruff作为linter，但继续使用isort扩展排序导入，可以通过以下settings.json禁用Ruff的导入排序功能：

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  },
  "ruff.organizeImports": false
}

如果你想在保存时运行Ruff，但避免允许其他扩展在保存时运行，可以通过以下settings.json使用Ruff的作用域source.fixAll和source.organizeImports操作：

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  }
}

如果你想运行Ruff，但禁用代码格式化（由Ruff或其他格式化工具执行），请确保在settings.json中取消设置editor.defaultFormatter：

{
  "[python]": {
    "editor.defaultFormatter": null,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    }
  }
}

使用基于Rust的语言服务器

如果满足以下条件，Ruff扩展将自动使用基于Rust的语言服务器（ruff server）：

1. ruff可执行文件的版本至少为0.5.3
2. ruff.nativeServer设置为auto（默认）
3. 未启用任何仅适用于基于Python的语言服务器的设置（即在设置文档中标记为"未被原生语言服务器使用"的设置）。

你可以通过将nativeServer设置为on或off来显式启用或禁用基于Rust的语言服务器。如果设置为off，扩展将使用基于Python的语言服务器（ruff-lsp）。

{
  "ruff.nativeServer": "on"
}

基于Rust的语言服务器直接内置于Ruff中，比基于Python的语言服务器更快、功能更全面。

使用原生服务器可能需要对你的VS Code配置进行更改，因为某些设置不受支持；更多信息请参见配置Ruff。

配置Ruff

Ruff VS Code 扩展将遵循您项目中 pyproject.toml、ruff.toml 或 .ruff.toml 文件中定义的任何 Ruff 配置（参见：Ruff 文档中的配置 Ruff）。 通常，我们建议通过 pyproject.toml 或 ruff.toml 配置 Ruff，以便在 VS Code 扩展和命令行工具之间，以及项目所有贡献者之间共享配置。

基于 Rust 的语言服务器

如果您使用基于 Rust 的语言服务器（ruff server），可以直接在 VS Code 中配置一些常见设置，如 ruff.lineLength（配置 linter 和格式化器的行长度）或 ruff.lint.select（配置启用的 lint 规则）：

{
  "ruff.lineLength": 88,
  "ruff.lint.select": ["C", "E", "F", "W"]
}

要使用自定义配置文件，请将 ruff.configuration 设置为 ruff.toml 或 pyproject.toml 文件的路径：

{
  "ruff.configuration": "/path/to/ruff.toml"
}

最后，要在所有项目中使用通用的 Ruff 配置，请考虑创建一个用户特定的 pyproject.toml 或 ruff.toml 文件，如 FAQ 中所述。

基于 Python 的语言服务器（ruff-lsp）

如果您使用默认的基于 Python 的语言服务器，可以在 settings.json 中使用 ruff.lint.args 和 ruff.format.args 设置来向 Ruff 传递命令行参数。

例如，要在 VS Code 中启用 pyupgrade 规则集，请在 settings.json 中添加以下内容：

{
  "ruff.lint.args": ["--extend-select=UP"]
}

要完全覆盖 VS Code 扩展的 Ruff 配置，并覆盖任何本地 pyproject.toml 文件或类似文件，您可以向 Ruff CLI 传递自定义的 --config 参数，同样使用 settings.json 中的 ruff.lint.args 和 ruff.format.args 选项：

{
  "ruff.lint.args": ["--config=/path/to/ruff.toml"],
  "ruff.format.args": ["--config=/path/to/ruff.toml"]
}

最后，要在所有项目中使用通用的 Ruff 配置，请考虑创建一个用户特定的 pyproject.toml 或 ruff.toml 文件，如 FAQ 中所述。

命令

命令	描述
Ruff: 修复所有可自动修复的问题	修复所有可自动修复的问题。
Ruff: 格式化导入	整理导入。
Ruff: 格式化文档	格式化整个文档。
Ruff: 重启服务器	强制重启 linter 服务器。
Ruff: 打印调试信息（仅限原生服务器）	打印有关原生服务器的调试信息。
Ruff: 显示日志	打开 Ruff 输出通道。

要求

此扩展需要支持 Python 3.7+ 的 VSCode Python 扩展版本。Ruff 本身兼容 Python 3.7 到 3.13。

故障排除

如果您遇到任何扩展或语言服务器的问题，请参阅 VS Code 输出面板中的日志。您可以通过运行 Ruff: 显示日志 命令访问日志。

默认情况下，输出面板只包含扩展的日志。要启用来自语言服务器的日志，请在 settings.json 中将 trace.server 设置为 messages：

{
  "ruff.trace.server": "messages"
}

跟踪值也可以设置为 verbose 以获取更详细的日志。如果您使用基于 Rust 的语言服务器，可以使用 ruff.logLevel 设置控制服务器的日志级别，使用 ruff.logFile 将日志写入文件而不是输出面板。

扩展还在状态栏中显示某些信息。可以将其固定到状态栏作为永久项目。

<details><summary><b>如何在 VS Code 工具栏中固定 Ruff 状态项？</b></summary> <img width="677" alt="在 VS Code 编辑器工具栏上固定 'Ruff' 状态项的说明" src="https://github.com/user-attachments/assets/fae75b6a-ae3f-4933-ad9c-61c6374f435b" > </details>

状态栏项显示语言服务器的状态，特别是它是否使用基于 Rust 的语言服务器（Ruff (native)）或基于 Python 的语言服务器（Ruff (ruff-lsp)）。还可以点击它打开 Ruff 输出通道。

许可证

MIT

<div align="center"> <a target="_blank" href="https://astral.sh" style="background:none"> <img height="24px" src="https://yellow-cdn.veclightyear.com/835a84d5/0501c916-63a5-47d7-9ce1-3972607ba82d.png"> </a> </div>