Python
/
ruff
mirror of https://github.com/astral-sh/ruff
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
ruff/docs/integrations.md

13 KiB
Raw Blame History

Integrations

Editor Integrations

Ruff Language Server (ruff server)

The Ruff language server, also known as ruff server, is what powers the diagnostic and formatting capabilities of Ruff's VS Code extension and other editors. It is a single, common backend for editor integrations built directly into Ruff, and a direct replacement for ruff-lsp, our previous language server. You can read more about ruff server in the v0.4.5 blog post.

ruff server uses the LSP (Language Server Protocol), and as such works with any editor that supports this protocol. VS Code, Neovim, Helix, and Kate all have official, documented support for ruff server. Other editors may support the older ruff-lsp server - see the Setup guide in ruff-lsp for more details.

VS Code (Official)

Download the Ruff VS Code extension, which supports fix actions, import sorting, and more.

By default, the extension will attempt to use the ruff executable installed on your local system, and will use a bundled executable if that's not available. If ruff is v0.4.5 or later, the extension will automatically use ruff server - otherwise, it will use ruff-lsp.

To learn more about configuring the extension, and the settings available for the extension, refer to Configuring Ruff in the ruff-vscode documentation.

Vim & Neovim (Official)

Using nvim-lspconfig

  1. Install nvim-lspconfig.
  2. Setup nvim-lspconfig with the suggested configuration.
  3. Finally, add this to your init.lua:
require('lspconfig').ruff.setup {}

See nvim-lspconfig's server configuration guide for more details on how to configure the server from there.

!IMPORTANT

If you have the older language server (ruff-lsp) configured in Neovim, make sure to disable it to prevent any conflicts.

Tips

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' then
    -- Disable hover in favor of Pyright
    client.server_capabilities.hoverProvider = false
  end
end

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

If you'd like to use Ruff exclusively for linting, formatting, and import organization, you can disable those capabilities for 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 = { '*' },
      },
    },
  },
}

By default, Ruff will not show any logs. To enable logging in Neovim, you'll need to set the RUFF_TRACE environment variable to either messages or verbose:

require('lspconfig').ruff.setup {
  cmd_env = { RUFF_TRACE = "messages" }
}

You can set the log level in settings:

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

It's also possible to divert Ruff's logs to a separate file with the logFile setting:

require('lspconfig').ruff.setup {
  cmd_env = { RUFF_TRACE = "messages" },
  init_options = {
    settings = {
      logLevel = "debug",
      logFile = "~/.local/state/nvim/ruff.log"
    }
  }
}

The logFile path supports tildes and environment variables.

Helix (Official)

First, open the language configuration file for Helix. On Linux and macOS, this will be at ~/.config/helix/languages.toml, and on Windows this will be at %AppData%\helix\languages.toml.

Add the language server by adding:

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

Then, you'll register the language server as the one to use with Python. If you don't already have a language server registered to use with Python, add this to languages.toml:

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

Otherwise, if you already have language-servers defined, you can simply add "ruff" to the list. For example, if you already have pylsp as a language server, you can modify the language entry as follows:

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

!NOTE

Multiple language servers for a single language are only supported in Helix version 23.10 and later.

Once you've set up the server, you should see diagnostics in your Python files. Code actions and other LSP features should also be available.

A screenshot showing an open Python file in Helix with highlighted diagnostics and a code action dropdown menu open This screenshot is using select=["ALL]" for demonstration purposes.

If you want to, as an example, turn on auto-formatting, add auto-format = true:

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

See the Helix documentation for more settings you can use here.

You can pass settings into ruff server using [language-server.ruff.config.settings]. For example:

[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

By default, Ruff does not log anything to Helix. To enable logging, set the RUFF_TRACE environment variable to either messages or verbose.

[language-server.ruff]
command = "ruff"
args = ["server", "--preview"]
environment = { "RUFF_TRACE" = "messages" }

!NOTE

RUFF_TRACE=verbose does not enable Helix's verbose mode by itself. You'll need to run Helix with -v for verbose logging.

To change the log level for Ruff (which is info by default), use the logLevel setting:

[language-server.ruff]
command = "ruff"
args = ["server", "--preview"]
environment = { "RUFF_TRACE" = "messages" }

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

You can also divert Ruff's logs to a separate file with the logFile setting:

[language-server.ruff]
command = "ruff"
args = ["server", "--preview"]
environment = { "RUFF_TRACE" = "messages" }

[language-server.ruff.config.settings]
logLevel = "debug"
logFile = "~/.cache/helix/ruff.log"

The logFile path supports tildes and environment variables.

Kate (Official)

  1. Activate the LSP Client plugin.
  2. Setup LSP Client as desired.
  3. Finally, add this to Settings -> Configure Kate -> LSP Client -> User Server Settings:
{
  "servers": {
    "python": {
      "command": ["ruff", "server", "--preview"],
      "url": "https://github.com/astral-sh/ruff",
      "highlightingModeRegex": "^Python$",
      "settings": {}
    }
  }
}

See LSP Client documentation for more details on how to configure the server from there.

!IMPORTANT

Kate's LSP Client plugin does not support multiple servers for the same language.

PyCharm (External Tool)

Ruff can be installed as an External Tool in PyCharm. Open the Preferences pane, then navigate to "Tools", then "External Tools". From there, add a new tool with the following configuration:

Install Ruff as an External Tool

Ruff should then appear as a runnable action:

Ruff as a runnable action

PyCharm (Unofficial)

Ruff is also available as the Ruff plugin on the IntelliJ Marketplace (maintained by @koxudaxi).

Emacs (Unofficial)

Ruff is available as flymake-ruff on MELPA:

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

Ruff is also available as emacs-ruff-format:

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

Alternatively, it can be used via the Apheleia formatter library, by setting this configuration:

(add-to-list 'apheleia-mode-alist '(python-mode . ruff))
(add-to-list 'apheleia-mode-alist '(python-ts-mode . ruff))

TextMate (Unofficial)

Ruff is also available via the textmate2-ruff-linter bundle for TextMate.

Other Integrations

pre-commit

Ruff can be used as a pre-commit hook via ruff-pre-commit:

- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff version.
  rev: v0.4.10
  hooks:
    # Run the linter.
    - id: ruff
    # Run the formatter.
    - id: ruff-format

To enable lint fixes, add the --fix argument to the lint hook:

- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff version.
  rev: v0.4.10
  hooks:
    # Run the linter.
    - id: ruff
      args: [ --fix ]
    # Run the formatter.
    - id: ruff-format

To run the hooks over Jupyter Notebooks too, add jupyter to the list of allowed filetypes:

- repo: https://github.com/astral-sh/ruff-pre-commit
  # Ruff version.
  rev: v0.4.10
  hooks:
    # Run the linter.
    - id: ruff
      types_or: [ python, pyi, jupyter ]
      args: [ --fix ]
    # Run the formatter.
    - id: ruff-format
      types_or: [ python, pyi, jupyter ]

When running with --fix, Ruff's lint hook should be placed before Ruff's formatter hook, and before Black, isort, and other formatting tools, as Ruff's fix behavior can output code changes that require reformatting.

When running without --fix, Ruff's formatter hook can be placed before or after Ruff's lint hook.

(As long as your Ruff configuration avoids any linter-formatter incompatibilities, ruff format should never introduce new lint errors, so it's safe to run Ruff's format hook after ruff check --fix.)

mdformat (Unofficial)

mdformat is capable of formatting code blocks within Markdown. The mdformat-ruff plugin enables mdformat to format Python code blocks with Ruff.

GitHub Actions

GitHub Actions has everything you need to run Ruff out-of-the-box:

name: CI
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install ruff          
      # Update output format to enable automatic inline annotations.
      - name: Run Ruff
        run: ruff check --output-format=github .

Ruff can also be used as a GitHub Action via ruff-action.

By default, ruff-action runs as a pass-fail test to ensure that a given repository doesn't contain any lint rule violations as per its configuration. However, under-the-hood, ruff-action installs and runs ruff directly, so it can be used to execute any supported ruff command (e.g., ruff check --fix).

ruff-action supports all GitHub-hosted runners, and can be used with any published Ruff version (i.e., any version available on PyPI).

To use ruff-action, create a file (e.g., .github/workflows/ruff.yml) inside your repository with:

name: Ruff
on: [ push, pull_request ]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: chartboost/ruff-action@v1

Alternatively, you can include ruff-action as a step in any other workflow file:

      - uses: chartboost/ruff-action@v1

ruff-action accepts optional configuration parameters via with:, including:

  • version: The Ruff version to install (default: latest).
  • args: The command-line arguments to pass to Ruff (default: "check").
  • src: The source paths to pass to Ruff (default: ".").

For example, to run ruff check --select B ./src using Ruff version 0.0.259:

- uses: chartboost/ruff-action@v1
  with:
    version: 0.0.259
    args: check --select B
    src: "./src"