Ruff linting plugin for pylsp

Common errors

• Plugin 'ruff' did not respond in time / Ruff not running in editor

  cause The `ruff` executable is not found in the system's PATH, or `python-lsp-server` and `python-lsp-ruff` are not installed within the same Python virtual environment.
  fix Ensure `ruff` is installed (`pip install ruff`) and accessible, and that both `python-lsp-server` and `python-lsp-ruff` are installed in the *same* virtual environment where your LSP client expects them. Reinstalling all three into a fresh virtual environment is a common fix.

• Code formatting not working as expected / Imports are not sorted automatically

  cause Since `python-lsp-ruff` v2.0.0, the default import sorting functionality was removed when `ruff format` was integrated.
  fix Add `"format": ["I"]` to your `ruff` formatting configuration within your LSP client settings to re-enable import sorting.

• Custom linting rules or ignores in LSP client settings are being ignored

  cause A `pyproject.toml` or `ruff.toml` file in the project root overrides `ruff` configurations provided via the LSP client's settings.
  fix Configure `ruff`'s rules (e.g., `select`, `ignore`, `line-length`) directly in your `pyproject.toml` (under `[tool.ruff.lint]`) or `ruff.toml` file to ensure they are respected by the LSP server.

• Linter/formatter not working for Jupyter notebooks (.ipynb files)

  cause Older versions of `python-lsp-ruff` or `ruff` might struggle with `.ipynb` file extensions, preventing proper detection as Python code by the linter/formatter.
  fix Update both `python-lsp-ruff` and `ruff` to their latest versions. Ensure your LSP client and any `jupyter-lsp` integrations are also updated. Some specific editor configurations might be needed for full notebook support.

Warnings

• breaking Version 2.0.0 introduced breaking changes to code formatting. It now uses `ruff format` directly, and the default import sorting was removed.
  Fix: To enable import sorting, add `format = ['I']` to your `ruff` configuration within your LSP client settings.
• breaking Versions 2.1.0 and 1.6.0 introduced breaking compatibility requirements with `ruff`. Older `python-lsp-ruff` versions might not work with newer `ruff` versions, and vice-versa.
  Fix: Ensure that your installed `ruff` version meets the minimum requirement specified by `python-lsp-ruff` (e.g., `ruff>=0.2.0` for `python-lsp-ruff>=2.1.0`). If using an older `ruff` (<0.1.0), you might need to pin `python-lsp-ruff==1.5.3`.
• gotcha Ruff itself ships with a built-in LSP server (`ruff-lsp` or `ruff server`) since `ruff>0.4.5`. This can be confused with `python-lsp-ruff`, which is a plugin for `python-lsp-server`. They serve different integration patterns.
  Fix: Understand your LSP setup: if you use `python-lsp-server` for multiple language features, `python-lsp-ruff` is the correct choice to integrate Ruff. If you primarily want Ruff's features as a standalone LSP, consider `ruff-lsp` directly.
• gotcha When a `pyproject.toml` or `ruff.toml` file is present in your project, `python-lsp-ruff` will often defer to its configuration, ignoring some options passed via `pylsp` settings.
  Fix: Prioritize configuring Ruff directly in your `pyproject.toml` or `ruff.toml` for project-specific settings to ensure consistent behavior across tools and contributors.
• gotcha `python-lsp-ruff` disables other linters/formatters (e.g., `pycodestyle`, `pyflakes`, `mccabe`, `autopep8`, `yapf`, `flake8`, `pyls_isort`) by default to avoid duplicate diagnostics.
  Fix: If you need to use these other tools alongside Ruff, you must explicitly re-enable them in your LSP client's configuration, ensuring no rule conflicts exist.

Install

• pip install python-lsp-server ruff python-lsp-ruff Install in same virtual environment

Imports

• Not directly imported
  python-lsp-ruff is a plugin for python-lsp-server and is not imported or used directly in application code. Its functionality is exposed via the Language Server Protocol client (e.g., IDE/editor configuration).

Quickstart

After installing `python-lsp-server`, `ruff`, and `python-lsp-ruff` in the same virtual environment, configure your LSP client (editor/IDE) to enable the Ruff plugin for `python-lsp-server`. This typically involves a JSON-like configuration for the language server. The example above shows how to enable Ruff for linting and formatting, explicitly re-enabling import sorting ('I') due to a breaking change in v2.0.0, and disabling other common Python linters to prevent conflicts. Remember to adjust paths and specific settings (e.g., `target-version`, `select`, `ignore`) according to your `ruff` configuration or `pyproject.toml`.

{  
  "python": {  
    "linting": {  
      "ruff": {  
        "enabled": true,  
        "config": "/path/to/pyproject.toml"  
      }  
    },  
    "formatting": {  
      "ruff": {  
        "enabled": true,  
        "format": ["I"]  
      }  
    },  
    "plugins": {  
      "pycodestyle": {"enabled": false},  
      "pyflakes": {"enabled": false}  
    }  
  }
}