GitHub - astral-sh/ruff-lsp: A Language Server Protocol implementation for Ruff. (original) (raw)

Warning

ruff-lsp is deprecated. Please switch to the native language server (ruff server). Refer to the setup guide on how to set up the native language server and the migration guide on how to migrate the settings.

Feel free to comment on the GitHub discussion to ask questions or share feedback.

ruff-lsp

Ruff image image image Actions status

Note

As of Ruff v0.4.5, Ruff ships with a built-in language server written in Rust: ⚡ ruff server ⚡

ruff server supports the same feature set as ruff-lsp, but with superior performance and no installation required. ruff server was marked as stable in Ruff v0.5.3.

See the documentation for more.

A Language Server Protocol implementation forRuff, an extremely fast Python linter and code formatter, written in Rust.

Ruff can be used to replace Flake8 (plus dozens of plugins), Black, isort, pyupgrade, and more, all while executing tens or hundreds of times faster than any individual tool.

ruff-lsp enables Ruff to be used in any editor that supports the LSP, including Neovim,Sublime Text, Emacs and more. For Visual Studio Code, check out theRuff VS Code extension.

ruff-lsp supports surfacing Ruff diagnostics and providing Code Actions to fix them, but is intended to be used alongside another Python LSP in order to support features like navigation and autocompletion.

Highlights

"Quick Fix" actions for auto-fixable violations (like unused imports)

Using the "Quick Fix" action to fix a violation

"Fix all": automatically fix all auto-fixable violations

Using the "Fix all" action to fix all violations

"Format Document": Black-compatible code formatting

Using the "Format Document" action to format Python source code

"Organize Imports": isort-compatible import sorting

Using the "Organize Imports" action to sort and deduplicate Python imports

Installation

ruff-lsp is available as ruff-lsp on PyPI:

Community packages

An Alpine Linux packageis available in the testing repository:

An Arch Linux package is available in the Extra repository:

Setup

Once installed, ruff-lsp can be used with any editor that supports the Language Server Protocol, including Neovim, Emacs, Sublime Text, and more.

Example: Neovim

To use ruff-lsp with Neovim, follow these steps:

  1. Install ruff-lsp from PyPI along with nvim-lspconfig.
  2. Set up the Neovim LSP client using the suggested configuration (:h lspconfig-keybindings).
  3. Finally, configure ruff-lsp in your init.lua:

-- Configure ruff-lsp. -- See: https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#ruff_lsp -- For the default config, along with instructions on how to customize the settings require('lspconfig').ruff_lsp.setup { init_options = { settings = { -- Any extra CLI arguments for ruff go here. args = {}, } } }

Upon successful installation, you should see Ruff's diagnostics surfaced directly in your editor:

Code Actions available in Neovim

Note that if you're using Ruff alongside another LSP (like Pyright), you may want to defer to that LSP for certain capabilities, like textDocument/hover:

local on_attach = function(client, bufnr) if client.name == 'ruff_lsp' then -- Disable hover in favor of Pyright client.server_capabilities.hoverProvider = false end end

require('lspconfig').ruff_lsp.setup { on_attach = on_attach, }

And, if you'd like to use Ruff exclusively for linting, formatting, and organizing imports, you can disable those capabilities in 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 also integrates with coc.nvim:

{ "languageserver": { "ruff-lsp": { "command": "ruff-lsp", "filetypes": [ "python" ] } } }

Example: Sublime Text

To use ruff-lsp with Sublime Text, install Sublime Text's LSPand LSP-ruff package.

Upon successful installation, you should see errors surfaced directly in your editor:

Code Actions available in Sublime Text

Example: Helix

To use ruff-lsp with Helix, add something like the following to~/.config/helix/languages.toml (in this case, with auto-format enabled):

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

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

Upon successful installation, you should see errors surfaced directly in your editor:

As of v23.10, Helix supports the use of multiple language servers for a given language. This enables, for example, the use of ruff-lsp alongside a language server like pyright:

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

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

[language-server.ruff.config.settings] args = ["--ignore", "E501"]

Example: Lapce

To use ruff-lsp with Lapce, install the lapce-ruff-lspplugin (which wraps ruff-lsp) from the Lapce plugins panel.

Upon successful installation, you should see errors surfaced directly in your editor:

Example: Kate

To use ruff-lsp with Kate, add something like the following to the LSP client's settings.json:

{ "servers": { "python": { "command": ["ruff-lsp"], "url": "https://github.com/astral-sh/ruff-lsp", "highlightingModeRegex": "^Python$" } } }

Fix safety

Ruff's automatic fixes are labeled as "safe" and "unsafe". By default, the "Fix all" action will not apply unsafe fixes. However, unsafe fixes can be applied manually with the "Quick fix" action. Application of unsafe fixes when using "Fix all" can be enabled by setting unsafe-fixes = true in your Ruff configuration file or adding--unsafe-fixes flag to the "Lint args" setting.

See the Ruff fix docs for more details on how fix safety works.

Jupyter Notebook Support

ruff-lsp has support for Jupyter Notebooks via the Notebook Document Synchronization capabilities of the Language Server Protocol which were added in 3.17. This allows ruff-lsp to provide full support for all of the existing capabilities available for Python files in Jupyter Notebooks, including diagnostics, code actions, and formatting.

This requires clients, such as Visual Studio Code, to support the notebook-related capabilities. In addition to the editor support, it also requires Ruff version v0.1.3 or later.

Settings

The exact mechanism by which settings will be passed to ruff-lsp will vary by editor. However, the following settings are supported:

Settings Default Description
codeAction.disableRuleComment.enable true Whether to display Quick Fix actions to disable rules via noqa suppression comments.
codeAction.fixViolation.enable true Whether to display Quick Fix actions to autofix violations.
fixAll true Whether to register Ruff as capable of handling source.fixAll actions.
format.args [] Additional command-line arguments to pass to ruff format, e.g., "args": ["--config=/path/to/pyproject.toml"]. Supports a subset of Ruff's command-line arguments, ignoring those that are required to operate the LSP, like --force-exclude and --verbose.
ignoreStandardLibrary true Whether to ignore files that are inferred to be part of the Python standard library.
interpreter [] Path to a Python interpreter to use to run the linter server.
lint.args [] Additional command-line arguments to pass to ruff check, e.g., "args": ["--config=/path/to/pyproject.toml"]. Supports a subset of Ruff's command-line arguments, ignoring those that are required to operate the LSP, like --force-exclude and --verbose.
lint.enable true Whether to enable linting. Set to false to use Ruff exclusively as a formatter.
lint.run onType Run Ruff on every keystroke (onType) or on save (onSave).
logLevel error Sets the tracing level for the extension: error, warn, info, or debug.
organizeImports true Whether to register Ruff as capable of handling source.organizeImports actions.
path [] Path to a custom ruff executable, e.g., ["/path/to/ruff"].
showSyntaxErrors true Whether to show syntax error diagnostics. New in Ruff v0.5.0

Development

Release

License

MIT