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 for Ruff, 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 the
Ruff 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.
ruff-lsp
is available as ruff-lsp
on PyPI:
pip install ruff-lsp
An Alpine Linux package
is available in the testing
repository:
apk add ruff-lsp
An Arch Linux package is
available in the Extra
repository:
pacman -S ruff-lsp
Once installed, ruff-lsp
can be used with any editor that supports the Language Server Protocol,
including Neovim, Emacs, Sublime Text, and more.
To use ruff-lsp
with Neovim, follow these steps:
- Install
ruff-lsp
from PyPI along withnvim-lspconfig
. - Set up the Neovim LSP client using the suggested configuration (
:h lspconfig-keybindings
). - Finally, configure
ruff-lsp
in yourinit.lua
:
-- Configure `ruff-lsp`.
-- See: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.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:
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"
]
}
}
}
To use ruff-lsp
with Sublime Text, install Sublime Text's LSP
and LSP-ruff package.
Upon successful installation, you should see errors surfaced directly in your editor:
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"]
To use ruff-lsp
with Lapce, install the lapce-ruff-lsp
plugin (which wraps ruff-lsp
) from the Lapce plugins panel.
Upon successful installation, you should see errors surfaced directly in your editor:
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$"
}
}
}
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.
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.
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 |
- Install
just
, or see thejustfile
for corresponding commands. - Create and activate a virtual environment (e.g.,
python -m venv .venv && source .venv/bin/activate
). - Install development dependencies (
just install
). To run thetest_format.py
test, you need to install a custom ruff build with--features format
, e.g.maturin develop --features format -m ../ruff/crates/ruff_cli/Cargo.toml
. - To automatically format the codebase, run:
just fmt
. - To run lint and type checks, run:
just check
. - To run tests, run:
just test
. This is just a wrapper around pytest, which you can use as usual.
- Bump the version in
ruff_lsp/__init__.py
. - Make sure you use Python 3.7 installed and as your default Python.
- Run
python -m venv .venv
to create a venv and activate it. - Run
python -m pip install pip-tools
to installpip-tools
. - Run
rm requirements.txt requirements-dev.txt
and thenjust lock
to update ruff. - Create a new PR and merge it.
- Create a new Release, enter
v0.0.x
(wherex
is the new version) into the Choose a tag selector. Click Generate release notes, curate the release notes and publish the release. - The Release workflow publishes the LSP to PyPI.
MIT