# [Settings](#settings)

The Ruff Language Server accepts settings to customize its behavior and can use an existing `pyproject.toml` or `ruff.toml` file to configure the linter and formatter. Provide these settings when initializing the server. VS Code provides a UI for them, while other editors may require manual configuration. The [setup](../setup/) section explains where to place the settings for each editor.

## [Top-level](#top-level)

### [`configuration`](#configuration)

The `configuration` setting allows you to configure editor-specific Ruff behavior. This can be done in one of the following ways:

1. **Configuration file path:** Specify the path to a `ruff.toml` or `pyproject.toml` file that contains the configuration. User home directory and environment variables will be expanded.
1. **Inline JSON configuration:** Directly provide the configuration as a JSON object.

Added in Ruff `0.9.8`

The **Inline JSON configuration** option was introduced in Ruff `0.9.8`.

The default behavior, if `configuration` is unset, is to load the settings from the project's configuration (a `ruff.toml` or `pyproject.toml` in the project's directory), consistent with when running Ruff on the command-line.

The [`configurationPreference`](#configurationpreference) setting controls the precedence if both an editor-provided configuration (`configuration`) and a project level configuration file are present.

#### [Resolution order](#configuration_resolution_order)

With the default `"editorFirst"` configuration preference, Ruff prioritizes the three sources of configuration as follows (from highest to lowest):

1. **Specific settings:** Individual settings like [`lineLength`](#linelength) or [`lint.select`](#select) defined in the editor
1. [**`ruff.configuration`**](#configuration): Settings provided via the [`configuration`](#configuration) field (either a path to a configuration file or an inline configuration object)
1. **Configuration file:** Settings defined in a `ruff.toml` or `pyproject.toml` file in the project's directory (if present)

For example, if the line length is specified in all three sources, Ruff will use the value from the [`lineLength`](#linelength) setting.

**Default value**: `null`

**Type**: `string` (path to a configuration file) or `object` (inline configuration)

**Example usage**:

*Using configuration file path:*

```
{
    "ruff.configuration": "~/path/to/ruff.toml"
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      configuration = "~/path/to/ruff.toml"
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "configuration": "~/path/to/ruff.toml"
        }
      }
    }
  }
}
```

*Using inline configuration:*

```
{
    "ruff.configuration": {
        "lint": {
            "unfixable": ["F401"],
            "extend-select": ["TID251"],
            "flake8-tidy-imports": {
                "banned-api": {
                    "typing.TypedDict": {
                        "msg": "Use `typing_extensions.TypedDict` instead"
                    }
                }
            }
        },
        "format": {
            "quote-style": "single"
        }
    }
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      configuration = {
        lint = {
          unfixable = {"F401"},
          ["extend-select"] = {"TID251"},
          ["flake8-tidy-imports"] = {
            ["banned-api"] = {
              ["typing.TypedDict"] = {
                msg = "Use `typing_extensions.TypedDict` instead"
              }
            }
          }
        },
        format = {
          ["quote-style"] = "single"
        }
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "configuration": {
            "lint": {
              "unfixable": ["F401"],
              "extend-select": ["TID251"],
              "flake8-tidy-imports": {
                "banned-api": {
                  "typing.TypedDict": {
                    "msg": "Use `typing_extensions.TypedDict` instead"
                  }
                }
              }
            },
            "format": {
              "quote-style": "single"
            }
          }
        }
      }
    }
  }
}
```

### [`configurationPreference`](#configurationpreference)

The strategy to use when resolving settings across VS Code and the filesystem. By default, editor configuration is prioritized over `ruff.toml` and `pyproject.toml` files.

- `"editorFirst"`: Editor settings take priority over configuration files present in the workspace.
- `"filesystemFirst"`: Configuration files present in the workspace take priority over editor settings.
- `"editorOnly"`: Ignore configuration files entirely i.e., only use editor settings.

**Default value**: `"editorFirst"`

**Type**: `"editorFirst" | "filesystemFirst" | "editorOnly"`

**Example usage**:

```
{
    "ruff.configurationPreference": "filesystemFirst"
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      configurationPreference = "filesystemFirst"
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "configurationPreference": "filesystemFirst"
        }
      }
    }
  }
}
```

### [`exclude`](#exclude)

A list of file patterns to exclude from linting and formatting. See [the documentation](https://docs.astral.sh/ruff/settings/#exclude) for more details.

**Default value**: `null`

**Type**: `string[]`

**Example usage**:

```
{
    "ruff.exclude": ["**/tests/**"]
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      exclude = { "**/tests/**" }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "exclude": ["**/tests/**"]
        }
      }
    }
  }
}
```

### [`lineLength`](#linelength)

The line length to use for the linter and formatter.

**Default value**: `null`

**Type**: `int`

**Example usage**:

```
{
    "ruff.lineLength": 100
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      lineLength = 100
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lineLength": 100
        }
      }
    }
  }
}
```

### [`fixAll`](#fixall)

Whether to register the server as capable of handling `source.fixAll` code actions.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.fixAll": false
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      fixAll = false
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "fixAll": false
        }
      }
    }
  }
}
```

### [`organizeImports`](#organizeimports)

Whether to register the server as capable of handling `source.organizeImports` code actions.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.organizeImports": false
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      organizeImports = false
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "organizeImports": false
        }
      }
    }
  }
}
```

### [`showSyntaxErrors`](#showsyntaxerrors)

*New in Ruff [v0.5.0](https://astral.sh/blog/ruff-v0.5.0#changes-to-e999-and-reporting-of-syntax-errors)*

Whether to show syntax error diagnostics.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.showSyntaxErrors": false
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      showSyntaxErrors = false
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "showSyntaxErrors": false
        }
      }
    }
  }
}
```

### [`logLevel`](#loglevel)

The log level to use for the server.

**Default value**: `"info"`

**Type**: `"trace" | "debug" | "info" | "warn" | "error"`

**Example usage**:

```
{
    "ruff.logLevel": "debug"
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      logLevel = "debug"
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "logLevel": "debug"
        }
      }
    }
  }
}
```

### [`logFile`](#logfile)

Path to the log file to use for the server.

If not set, logs will be written to stderr.

**Default value**: `null`

**Type**: `string`

**Example usage**:

```
{
    "ruff.logFile": "~/path/to/ruff.log"
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      logFile = "~/path/to/ruff.log"
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "logFile": "~/path/to/ruff.log"
        }
      }
    }
  }
}
```

## [`codeAction`](#codeaction)

Enable or disable code actions provided by the server.

### [`disableRuleComment.enable`](#disablerulecommentenable)

Whether to display Quick Fix actions to disable rules via `noqa` suppression comments.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.codeAction.disableRuleComment.enable": false
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      codeAction = {
        disableRuleComment = {
          enable = false
        }
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "codeAction": {
            "disableRuleComment": {
              "enable": false
            }
          }
        }
      }
    }
  }
}
```

### [`fixViolation.enable`](#fixviolationenable)

Whether to display Quick Fix actions to autofix violations.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.codeAction.fixViolation.enable": false
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      codeAction = {
        fixViolation = {
          enable = false
        }
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "codeAction": {
            "fixViolation": {
              "enable": false
            }
          }
        }
      }
    }
  }
}
```

## [`lint`](#lint)

Settings specific to the Ruff linter.

### [`enable`](#lint_enable)

Whether to enable linting. Set to `false` to use Ruff exclusively as a formatter.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.lint.enable": false
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      lint = {
        enable = false
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "enable": false
          }
        }
      }
    }
  }
}
```

### [`preview`](#lint_preview)

Whether to enable Ruff's preview mode when linting.

**Default value**: `null`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.lint.preview": true
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      lint = {
        preview = true
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "preview": true
          }
        }
      }
    }
  }
}
```

### [`select`](#select)

Rules to enable by default. See [the documentation](https://docs.astral.sh/ruff/settings/#lint_select).

**Default value**: `null`

**Type**: `string[]`

**Example usage**:

```
{
    "ruff.lint.select": ["E", "F"]
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      lint = {
        select = {"E", "F"}
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "select": ["E", "F"]
          }
        }
      }
    }
  }
}
```

### [`extendSelect`](#extendselect)

Rules to enable in addition to those in [`lint.select`](#select).

**Default value**: `null`

**Type**: `string[]`

**Example usage**:

```
{
    "ruff.lint.extendSelect": ["W"]
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      lint = {
        extendSelect = {"W"}
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "extendSelect": ["W"]
          }
        }
      }
    }
  }
}
```

### [`ignore`](#ignore)

Rules to disable by default. See [the documentation](https://docs.astral.sh/ruff/settings/#lint_ignore).

**Default value**: `null`

**Type**: `string[]`

**Example usage**:

```
{
    "ruff.lint.ignore": ["E4", "E7"]
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      lint = {
        ignore = {"E4", "E7"}
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "lint": {
            "ignore": ["E4", "E7"]
          }
        }
      }
    }
  }
}
```

## [`format`](#format)

Settings specific to the Ruff formatter.

### [`preview`](#format_preview)

Whether to enable Ruff's preview mode when formatting.

**Default value**: `null`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.format.preview": true
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      format = {
        preview = true
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "format": {
            "preview": true
          }
        }
      }
    }
  }
}
```

### [`backend`](#format_backend)

The backend to use for formatting files. The following options are available:

- `"internal"`: Use the built-in Ruff formatter
- `"uv"`: Use uv for formatting (requires uv >= 0.8.13)

For `internal`, the formatter version will match the selected Ruff version while for `uv`, the formatter version may differ.

Starting the server with `ruff server --untrusted-workspace` disables the uv backend. With this flag, the server always uses the internal formatter, regardless of this setting. This prevents workspace configuration from causing uv to execute untrusted code.

**Default value**: `"internal"`

**Type**: `"internal" | "uv"`

**Example usage**:

```
{
    "ruff.format.backend": "uv"
}
```

```
vim.lsp.config('ruff', {
  init_options = {
    settings = {
      format = {
        backend = "uv"
      }
    }
  }
})
```

```
{
  "lsp": {
    "ruff": {
      "initialization_options": {
        "settings": {
          "format": {
            "backend": "uv"
          }
        }
      }
    }
  }
}
```

## [VS Code specific](#vs-code-specific)

Additionally, the Ruff extension provides the following settings specific to VS Code. These settings are not used by the language server and are only relevant to the extension.

### [`enable`](#enable)

Whether to enable the Ruff extension. Modifying this setting requires restarting VS Code to take effect.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```
{
    "ruff.enable": false
}
```

### [`importStrategy`](#importstrategy)

Strategy for loading the `ruff` executable.

- `fromEnvironment` finds Ruff in the environment, falling back to the bundled version
- `useBundled` uses the version bundled with the extension

**Default value**: `"fromEnvironment"`

**Type**: `"fromEnvironment" | "useBundled"`

**Example usage**:

```
{
    "ruff.importStrategy": "useBundled"
}
```

### [`interpreter`](#interpreter)

A list of paths to Python interpreters. Even though this is a list, only the first interpreter is used.

The interpreter is used to find the `ruff` executable when [`ruff.importStrategy`](#importstrategy) is set to `fromEnvironment`.

**Default value**: `[]`

**Type**: `string[]`

**Example usage**:

```
{
    "ruff.interpreter": ["/home/user/.local/bin/python"]
}
```

### [`nativeServer`](#nativeserver)

Deprecated

This setting is deprecated as of Ruff 0.17. The Ruff extension will always use the native language server.

Whether to use the native language server, [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) or automatically decide between the two based on the Ruff version and extension settings.

**Default value**: `"auto"`

**Type**: `"on" | "off" | "auto" | true | false`

**Example usage**:

```
{
    "ruff.nativeServer": "on"
}
```

### [`path`](#path)

A list of paths to `ruff` executables.

The first executable in the list that exists is used. This setting takes precedence over the [`ruff.importStrategy`](#importstrategy) setting.

**Default value**: `[]`

**Type**: `string[]`

**Example usage**:

```
{
    "ruff.path": ["/home/user/.local/bin/ruff"]
}
```

### [`trace.server`](#traceserver)

The trace level for the language server. Refer to the [LSP specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#traceValue) for more information.

**Default value**: `"off"`

**Type**: `"off" | "messages" | "verbose"`

**Example usage**:

```
{
    "ruff.trace.server": "messages"
}
```