跳到内容

设置

我们针对不同的编辑器提供了专门的设置说明。如果您没有在列表中看到您的编辑器，且需要设置指南，请提交一个 Issue。

如果您是从 ruff-lsp 迁移配置，无论使用什么编辑器，都有一些设置发生了变化或不再可用。更多信息请参阅迁移指南。

注意

以下提供的设置说明是尽力而为的指南。如果您在编辑器中设置 Ruff 时遇到任何问题，请提交 Issue 以寻求帮助，并协助我们改进文档。

提示

无论使用哪种编辑器，都建议禁用旧版的语言服务器（ruff-lsp）以防止冲突。

VS Code

请从 VS Code 市场安装 Ruff 扩展。建议使用 Ruff 扩展 2024.32.0 或更高版本，以获得 Ruff 语言服务器的最佳体验。

有关 Ruff 扩展的更多文档，请参阅扩展仓库的 README。

Neovim

可以使用 nvim-lspconfig 插件在 Neovim 中配置 Ruff 语言服务器。安装 nvim-lspconfig 插件，按照其配置文档进行设置，并将以下内容添加到您的 init.lua 中：

require('lspconfig').ruff.setup({
  init_options = {
    settings = {
      -- Ruff language server settings go here
    }
  }
})

vim.lsp.config('ruff', {
  init_options = {
    settings = {
      -- Ruff language server settings go here
    }
  }
})

vim.lsp.enable('ruff')

注意

如果已安装的 nvim-lspconfig 版本包含了 neovim/nvim-lspconfig@70d1c2c 的更改，您需要使用 Ruff 0.5.3 或更高版本。

如果您在将 Ruff 与其他语言服务器（如 Pyright）同时使用，您可能希望将某些功能（例如 textDocument/hover）委托给该语言服务器处理。

vim.api.nvim_create_autocmd("LspAttach", {
  group = vim.api.nvim_create_augroup('lsp_attach_disable_ruff_hover', { clear = true }),
  callback = function(args)
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    if client == nil then
      return
    end
    if client.name == 'ruff' then
      -- Disable hover in favor of Pyright
      client.server_capabilities.hoverProvider = false
    end
  end,
  desc = 'LSP: Disable hover capability from Ruff',
})

如果您希望仅使用 Ruff 进行代码检查（linting）、格式化和整理导入，您可以禁用 Pyright 的相关功能。

require('lspconfig').pyright.setup {
  settings = {
    pyright = {
      -- Using Ruff's import organizer
      disableOrganizeImports = true,
    },
    python = {
      analysis = {
        -- Ignore all files for analysis to exclusively use Ruff for linting
        ignore = { '*' },
      },
    },
  },
}

默认情况下，Ruff 的日志级别设置为 info。要更改日志级别，您可以设置 logLevel 设置。

require('lspconfig').ruff.setup {
  init_options = {
    settings = {
      logLevel = 'debug',
    }
  }
}

默认情况下，Ruff 会将日志写入 stderr，这些日志可在 Neovim LSP 客户端的日志文件中查看（:lua vim.print(vim.lsp.get_log_path())）。也可以通过 logFile 设置将这些日志重定向到单独的文件。

要查看 Neovim 和 Ruff 之间的追踪日志，请将 Neovim LSP 客户端的日志级别设置为 debug。

vim.lsp.set_log_level('debug')
使用 Neovim 的 conform.nvim 插件。 
require("conform").setup({
    formatters_by_ft = {
        python = {
          -- To fix auto-fixable lint errors.
          "ruff_fix",
          -- To run the Ruff formatter.
          "ruff_format",
          -- To organize the imports.
          "ruff_organize_imports",
        },
    },
})
使用 Neovim 的 nvim-lint 插件。 
require("lint").linters_by_ft = {
  python = { "ruff" },
}
使用 Neovim 或 Vim 的 ALE 插件。 Neovim（使用 Lua） 
-- Linters
vim.g.ale_linters = { python = { "ruff" } }
-- Fixers
vim.g.ale_fixers = { python = { "ruff", "ruff_format" } }
Vim（使用 Vimscript） 
" Linters
let g:ale_linters = { "python": ["ruff"] }
" Fixers
let g:ale_fixers = { "python": ["ruff", "ruff_format"] }
对于修复程序，ruff 将运行 ruff check --fix（修复所有可自动修复的问题），而 ruff_format 将运行 ruff format。

Vim

可以使用 vim-lsp 插件在 Vim 中配置 Ruff 语言服务器。安装 vim-lsp 插件，并在 .vimrc 中使用以下代码注册服务器：

if executable('ruff')
    au User lsp_setup call lsp#register_server({
        \ 'name': 'ruff',
        \ 'cmd': {server_info->['ruff', 'server']},
        \ 'allowlist': ['python'],
        \ 'workspace_config': {},
        \ })
endif

有关如何配置语言服务器的更多详细信息，请参阅 vim-lsp 文档。

如果您将 Ruff 与其他 LSP（如 Pyright）同时使用，您可能希望通过将以下内容添加到 s:on_lsp_buffer_enabled() 函数中，将某些功能（例如 textDocument/hover）委托给该 LSP 处理。

function! s:on_lsp_buffer_enabled() abort
    " add your keybindings here (see https://github.com/prabirshrestha/vim-lsp?tab=readme-ov-file#registering-servers)

    let l:capabilities = lsp#get_server_capabilities('ruff')
    if !empty(l:capabilities)
      let l:capabilities.hoverProvider = v:false
    endif
endfunction

Ruff 也可通过 coc.nvim 的 coc-pyright 扩展使用。

Ruff 也可以仅用几行代码通过 efm 语言服务器进行集成。以下是使用 efm 将 Ruff 用于 Python 文件 linting 和格式化的示例配置。
tools:
  python-ruff:
    lint-command: "ruff check --stdin-filename ${INPUT} --output-format concise --quiet -"
    lint-stdin: true
    lint-formats:
      - "%f:%l:%c: %m"
    format-command: "ruff format --stdin-filename ${INPUT} --quiet -"
    format-stdin: true

Helix

打开 Helix 的 语言配置文件 并按如下方式添加语言服务器。

[language-server.ruff]
command = "ruff"
args = ["server"]

然后，将该语言服务器注册为 Python 使用的服务器。如果您还没有为 Python 注册任何语言服务器，请在 languages.toml 中添加以下内容：

[[language]]
name = "python"
language-servers = ["ruff"]

或者，如果您已经定义了 language-servers，则只需将 "ruff" 添加到列表中即可。例如，如果您已经拥有 pylsp 作为语言服务器，您可以按如下方式修改语言条目：

[[language]]
name = "python"
language-servers = ["ruff", "pylsp"]

注意

仅在 Helix 23.10 及更高版本中才支持为单一语言配置多个语言服务器。

例如，如果您想开启自动格式化，请添加 auto-format = true。

[[language]]
name = "python"
language-servers = ["ruff", "pylsp"]
auto-format = true

请参阅 Helix 文档 以获取更多可用设置。

您可以使用 [language-server.ruff.config.settings] 将设置传递给 ruff server。例如：

[language-server.ruff.config.settings]
lineLength = 80

[language-server.ruff.config.settings.lint]
select = ["E4", "E7"]
preview = false

[language-server.ruff.config.settings.format]
preview = true

默认情况下，Ruff 的日志级别设置为 info。要更改日志级别，您可以设置 logLevel 设置。

[language-server.ruff]
command = "ruff"
args = ["server"]

[language-server.ruff.config.settings]
logLevel = "debug"

您还可以使用 logFile 设置将 Ruff 的日志重定向到单独的文件。

要查看 Helix 和 Ruff 之间的追踪日志，请在启动 Helix 时传入 -v（verbose）标志。

hx -v path/to/file.py

Kate

  1. 激活 LSP Client 插件。
  2. 按需设置 LSP Client。
  3. 最后，将此内容添加到 Settings -> Configure Kate -> LSP Client -> User Server Settings：
{
  "servers": {
    "python": {
      "command": ["ruff", "server"],
      "url": "https://github.com/astral-sh/ruff",
      "highlightingModeRegex": "^Python$",
      "settings": {}
    }
  }
}

请参阅 LSP Client 文档 以了解更多关于如何从该处配置服务器的详细信息。

重要

Kate 的 LSP Client 插件不支持同一语言使用多个服务器。作为一种变通方法，您可以使用 python-lsp-server 配合 python-lsp-ruff 插件，以便将 Ruff 与其他语言服务器同时使用。请注意，此设置不会使用 服务器设置，因为 python-lsp-ruff 插件使用的是 ruff 可执行文件，而非语言服务器。

Sublime Text

要在 Sublime Text 中使用 Ruff，请安装 Sublime Text 的 LSP 和 LSP-ruff 插件包。

PyCharm

从 2025.3 版本开始，PyCharm 开箱即支持 Ruff。

  1. 在设置对话框中转到 Python | Tools | Ruff。

  2. 勾选 Enable 复选框。

  3. 在 Execution mode（执行模式）设置中，选择 PyCharm 搜索可执行文件的方式：

    Interpreter（解释器）模式：PyCharm 会搜索安装在您解释器中的可执行文件。若要为所选解释器安装 Ruff 包，请点击 Install Ruff。

    Path（路径）模式：PyCharm 会在 $PATH 中搜索可执行文件。如果未找到，您可以点击 Browse... 图标指定路径。

  4. 选择应启用的选项。

更多信息请参考 PyCharm 文档。

通过外部工具

Ruff 可作为 外部工具 安装在 PyCharm 中。打开 Preferences 面板，导航至 "Tools"，然后点击 "External Tools"。在其中添加一个配置如下的新工具：

Install Ruff as an External Tool

Ruff 随后将作为可运行的操作显示。

Ruff as a runnable action

通过第三方插件

Ruff 也可以作为 IntelliJ 市场上的 Ruff 插件使用（由 @koxudaxi 维护）。

Emacs

Ruff 可以通过 Emacs 核心中的 Eglot 作为语言服务器使用。要启用带有保存时自动格式化的 Ruff，请使用以下配置：

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(python-base-mode . ("ruff" "server"))))
(add-hook 'python-base-mode-hook
          (lambda ()
            (eglot-ensure)
            (add-hook 'after-save-hook 'eglot-format nil t)))

Ruff 在 MELPA 上以 flymake-ruff 的形式提供。

(require 'flymake-ruff)
(add-hook 'python-mode-hook #'flymake-ruff-load)

Ruff 也可作为 emacs-ruff-format 使用。

(require 'ruff-format)
(add-hook 'python-mode-hook 'ruff-format-on-save-mode)

或者，可以通过 Apheleia 格式化库，通过设置以下配置来使用它：

;; Replace default (black) to use ruff for sorting import and formatting.
(setf (alist-get 'python-mode apheleia-mode-alist)
      '(ruff-isort ruff))
(setf (alist-get 'python-ts-mode apheleia-mode-alist)
      '(ruff-isort ruff))

TextMate

Ruff 也可通过 TextMate 的 textmate2-ruff-linter 包使用。

Zed

Ruff 支持现已内置于 Zed 中（无需单独安装扩展）。

默认情况下，Zed 使用 Ruff 进行格式化和 linting。

要设置编辑器级别的 Ruff 选项，请在 settings.json 文件的 lsp.ruff.initialization_options.settings 键下提供 服务器设置。

{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          // Ruff server settings go here
          "lineLength": 80,
          "lint": {
            "extendSelect": ["I"],
          }
        }
      }
    }
  }
}

format_on_save 默认已启用。您可以通过在 settings.json 文件中更改 format_on_save 来禁用 Python 的此功能。

{
  "languages": {
    "Python": {
      "format_on_save": "off"
    }
  }
}

您可以配置 Ruff 在保存时修复 lint 违规和/或整理导入，方法是分别启用 source.fixAll.ruff 和 source.organizeImports.ruff 代码操作。

{
  "languages": {
    "Python": {
      "code_actions_on_format": {
        // Organize imports
        "source.organizeImports.ruff": true,
        // Fix all auto-fixable lint violations
        "source.fixAll.ruff": true
      }
    }
  }
}