ruff-lsp is deprecated; please upgrade to the native language server (ruff server)

[dhruvmanila]

Hey everyone,

ruff-lsp is marked as deprecated with the upcoming Ruff release, it will be archived with the release of Ruff 0.11. We suggest everyone to upgrade to the native server (⚡ ruff server ⚡).

ruff server supports the same feature set as ruff-lsp, but with superior performance and no installation required. It was first released in Ruff v0.3.5, announced as beta in Ruff 0.4.5 and marked as stable in Ruff 0.5.3.

Refer to the setup guide on how to set up the native language server for multiple editors and the migration guide on how to migrate the deprecated settings.

If you're unable to upgrade to the native server, feel free to comment on this discussion so that we can help.

[ilCatania]

I have this in my VScode settings.json, how do I convert it please?
Thank you

"ruff.lint.args": [ "--unfixable=F841,T201"]

I tried ctrl+space, copilot, migration guide, but couldn't figure it out. Sorry!

[dhruvmanila]

Currently, we support limited subset of the settings that can be set directly in the editor, they're mentioned on this page: https://docs.astral.sh/ruff/editors/settings/.

For your specific case, you could either set it on a per-project basis in a local pyproject.toml / ruff.toml file or set it globally using ruff.configuration setting i.e., create a file that has the common options for all the project (e.g., in ~/.config/ruff.toml) and provide the path as in "ruff.configuration": "~/.config/ruff.toml".

[ilCatania]

Ok, however my use case is slightly subtle: I want to set some settings only for the editor (VScode) but not in pyproject.toml nor in the global config, because I don't want the editor to remove unused variables or print statements when my users write exploratory code, but I do want them gone when they commit and trigger the pre commit hook.

So I guess I could put a ruff.toml in my project's .vscode/ directory, but then I am not sure how to specify a relative path in the settings.json sitting alongside it? My users might be checking out my project in an arbitrary directory...

[dhruvmanila]

I see, so it's more like project specific settings for the everyone working on it but only in an editor context.

So I guess I could put a ruff.toml in my project's .vscode/ directory, but then I am not sure how to specify a relative path in the settings.json sitting alongside it? My users might be checking out my project in an arbitrary directory...

I'd recommend doing this and providing the path using VS Code variables like:

{
	"ruff.configuration": "${workspaceFolder}/.vscode/ruff.toml"
}

[ilCatania]

Of course! That will work! Thank you

[kleynjan]

I am currently using ruff only by way of the official Ruff extension in VScode and fully configured in settings.json. I have looked at the ruff extension docs and the setup and migration guides but despite that it's not exactly clear to me how I should move to the 'native' ruff server and how I should migrate the settings I've built up over the years. In general, I'd appreciate it if we could have some stability and predictability in configuring Python extensions.

While I'm waiting for this mist to clear: is there a way to suppress the ruff-lsp deprecation warning?

[kleynjan]

For example, the docs say to add "ruff.nativeServer": "on" to the config.
The VScode settings editor reacts to this with the warning: "Deprecated: This setting has been deprecated with the deprecation of ruff-lsp. It was mainly used to provide a way to switch between the native language server and ruff-lsp during the transition period."

[MichaReiser]

Hmm, yeah, the warning about the setting isn't great. We should probably omit the warning if it is set to on.

[dhruvmanila]

Thanks for the feedback. I discussed this with Micha on Discord and we think it might be best to un-deprecate ruff.nativeServer specifically as it might still be useful during the deprecation period. Later, when ruff-lsp is actually removed, this setting will then be deprecated. Sorry for the churn.

[ksylvan]

Okay, here's a puzzle that I don't see how to fix with the new settings.

I have the following in VSCode settings:

"ruff.lint.args": [
            "--extend-select=DJ001,INP001,ANN201",
            "--config",
             "lint.flake8-annotations.ignore-fully-untyped=false"
]

because I want to see squiggles in VSCode for the flake8 untyped functions, and, at the same time, I have this in my ruff.toml because I want the CLI (and CI scripts) to pass without errors.

[lint.flake8-annotations]
ignore-fully-untyped = true 

How do I fix this?

[ksylvan]

I guess the best way is to add the arguments --config lint.flake8-annotations.ignore-fully-untyped=false when running the ruff cli (or in CI scripts)

[dhruvmanila]

I have the following in VSCode settings:

Assuming that these VS Code settings needs to be applied for all projects, you can create a central Ruff config file and provide a path to it via ruff.configuration:

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

The configuration file will only been seen by the editor and it'll merge the settings with the one in the project, if there is any. So, what you'll get is that in the editor, ignore-fully-untyped will be false while on the command-line it'll be true.

[tylerlaprade]

I see - the config-merging behavior wasn't clear to me from the migration guide. That should work, moving our existing overrides to a VSCode-only 2nd config file. Thanks @dhruvmanila!

[Aran-Fey]

I find the warning displayed in vscode very cryptic. My language server is set to "Pylance", and I only use ruff for formatting. I honestly have no clue why I'm seeing this warning at all or how to get rid of it. The setup guide pretty much just says to install the ruff extension and that's it. I can't find any useful information anywhere.

[dhruvmanila]

My problem with the warning itself is that I've never heard of ruff-lsp in my life, so I have no clue how it being deprecated affects me or why it requires me to do something. In theory it's nice that the warning links to 2 guides, but the guides themselves aren't helpful, so ultimately I'm just being sent on an odyssey to 3 different places that don't solve my problem.

Thank you, that's useful. I agree in retrospect that it was bad part of my end to include "ruff-lsp" in the deprecation warning as users might be unaware of the underlying tool that's being used in the VS Code extension. To give context, ruff-lsp is the implementation of LSP protocol which powers the VS Code extension. We introduced the same within Ruff itself which is available under the ruff server subcommand. I'll look into improving the message.

Does ruff-lsp simply refer to some legacy settings in settings.json such as "ruff.lint.args", and does migrating to the new ruff server just involve replacing these legacy settings with new ones ? Or are there any special setups ? The vscode warning message is clear to me, but I think the setup and migration guides in Ruff doc could be improved.

I've provided some context in my previous paragraph.

To some extent, yes, some settings have been deprecated and they need to be replaced with the new way of configuring. For your use-case related to ruff.lint.args, I'd suggest you to replace it with ruff.configuration. Feel free to ask any other questions you have.

[MichaReiser]

Should we update the message to differentiate between

a) Users that directly opted in using nativeServer: off and
b) Users that use deprecated settings

[FHU-yezi]

For now, what is the default settings if user removed this config?

[dhruvmanila]

@FHU-yezi Are you referring to ruff.lint.args or ruff.nativeServer? If it's the former, it should work as if you hadn't pass those arguments while invoking the ruff executable. And, if it's the latter, the extension would try to detect automatically between deprecated and the new language server based on the settings set and provide warnings if required.

[dhruvmanila]

Should we update the message to differentiate between

a) Users that directly opted in using nativeServer: off and b) Users that use deprecated settings

The setting is only relevant to the VS Code extension but the warning originates in ruff-lsp, I'll propose something tomorrow.

[copdips]

both of my vscode and ruff are on the latest version, but still got the warning, and don't know how to confirm I'm using ruff-lsp or ruff server?

In other words, how to not use ruff-lsp ?

Tried to add "ruff.nativeServer": "on" in settings.json, but got another warning:

Deprecated: This setting has been deprecated with the deprecation of ruff-lsp. It was mainly used to provide a way to switch between the native language server and ruff-lsp during the transition period.

[copdips]

ok, after replacing the legacy settings, there're no more vscode warnings, what I understand is that:

1. ruff server is auto activated with new ruff version, there's no switch button.
2. migration means removing old ruff settings in settings.json and updating them to the new sytanx

[dhruvmanila]

Tried to add "ruff.nativeServer": "on" in settings.json, but got another warning:

Deprecated: This setting has been deprecated with the deprecation of ruff-lsp. It was mainly used to provide a way to switch between the native language server and ruff-lsp during the transition period.

Refer to #15991 (comment) thread for more details on this but we've decided to un-deprecate ruff.nativeServer for now.

• ruff server is auto activated with new ruff version, there's no switch button.
• migration means removing old ruff settings in settings.json and updating them to the new sytanx

Yes, that's correct. This is useful feedback, thank you, I'll update the warning message to reflect this.

[hamdanal]

Thanks for the update. Please don't remove the old lsp before these issues with the new server astral-sh/ruff-vscode#593 and astral-sh/ruff-vscode#680 are fixed.

[charliermarsh]

We won't be able to make any progress on astral-sh/ruff-vscode#680 unless we have more information and/or a reproduction. My guess is it's an interaction with another extension, and not a Ruff LSP issue, but it's hard to say. If it's affecting you and you're able to share more information, please let us know.

[daireto]

Will you support more settings that can be set directly in the editor? For example, quote style, as well as the line length setting? I use three devices, so synchronizing these settings across all devices can be very helpful to me and those who also work on multiple devices.

[dhruvmanila]

Related astral-sh/ruff-vscode#6. Yes, we can add more settings based on user requests. Ideally, we'd want to mirror the Ruff configuration but it's a bit difficult, see astral-sh/ruff-vscode#260 (comment).

[vuki]

Please add at least the 'single quote' option to the configuration. Right now, this stops me from moving to the new server. A global ruff configuration file is not a convenient solution as it is not synchronized across different machines, unlike the VS Code configuration file.

[niccokunzmann]

Hi, I just saw this message pop up:

I was hoping that I can click one of the links and then, I know what to do to remove the message.

What I did is uninstall and install of the plugin and I was hoping that then disables the message but it does not - it just should go ahead with a new config. I sadly do not have the head space at the moment to skip though discussions to see what I should do. I will disable this message now and care for it when the next message says that something is actually broken. Then, I will uninstall the plugin again, install it and hope that that solves the problem - it working with the correct default parameters.

[dhruvmanila]

Apologies for this experience, I spent some time in improving the messages which should be released today and should provide a better experience overall.

Regardless, if you don't mind sharing your VS Code settings for Ruff, I'm happy to guide you on how to migrate them.

[niccokunzmann]

Hi, I appreciate the plugin and all the work put it. There is nothing for you to help me specifically. I was asked to give feedback and so I wanted to give feedback from the point of view of someone who might otherwise consider not to engage - so that you have that type of feedback, too. All is well and thank you for putting in the effort to maintain this!

[skurfer]

Hello. The only setting I use (in VSCode) is ruff.path, which is not listed as deprecated but still seems to use ruff-lsp and trigger the alert.

[skurfer]

This was due to the fact that the version of ruff the path pointed to was very old. Updating removed the alert.

I’ll leave this here for others who might be in the same situation.

[dhruvmanila]

Yeah, that's right. The native server was stabilized in 0.5.3, so if the extension resolves to using a Ruff version greater than or equal to that and there are no deprecated / removing settings used, the extension will automatically switch to the native server.

[aaron-skydio]

The thing that's blocking us from using the native server is this issue: astral-sh/ruff-lsp#335

We currently work around this with a wrapper script that rewrites calls to ruff format to also run ruff check --fixable=I,D --fix-only, to also run isort and docstring formatting fixes. And then we point ruff.path at this wrapper script. AFAICT, there's no way to achieve this with the native server; in VSCode, it's possible to attach additional actions to run on save, but not to attach additional actions to run on format (e.g. if you don't have formatOnSave turned on, or if you autoformat without saving)

[aaron-skydio]

Import sorting on save would probably be enough, the docstring formatting is less of an issue and I'd be happy moving to ruff server without that. It does sort of point to the more general request in astral-sh/ruff-lsp#335 since people may disagree on which fixes they want to run automatically with the formatter

[dhruvmanila]

Thanks for the feedback.

We do expose the formatting and auto-fixing diagnostics capabilities via commands (https://github.com/astral-sh/ruff-vscode#commands), so if it's possible to run commands on save (either builtin or via an extension) then these can be used to run both the formatter and apply available fixes.

Or, if the above is not possible we could expose a custom code action that formats the document like source.formatDocument or ruff.formatDocument which can then be used along with source.fixAll.ruff.

Note that either of the above approach doesn't allow you to specify a subset of fixes to apply i.e., the --fixable=I,D and that will need to be configured in a local config file. To resolve that, #12709 would need to be implemented.

[aaron-skydio]

Thanks! I was able to put this together with this keybind:

 {
    "command": "runCommands",
    "key": "ctrl+shift+i",
    "args": {
      "commands": [
        "editor.action.formatDocument",
        "ruff.executeOrganizeImports"
        // If you want autofix also - this won't let you specify a subset of rules (e.g. for only
        // docstring format rules) until https://github.com/astral-sh/ruff/issues/12709
        // "ruff.executeAutofix"
      ]
    },
    "when": "editorLangId == python"
  }

which replaces the Format Document keybind for python, to run format + isort

[aaron-skydio]

Note that either of the above approach doesn't allow you to specify a subset of fixes to apply i.e., the --fixable=I,D and that will need to be configured in a local config file. To resolve that, #12709 would need to be implemented.

Related to this - it seems like the fixable list set in the config file also affects what shows up in the Quick Fix menu - is there a way to mark fixable/unfixable rules just for the ruff.executeAutoFix command but not for the Quick Fix menu?

Not blocking us from moving to ruff server, but I didn't see an existing issue so I figured I'd continue here

[dhruvmanila]

which replaces the Format Document keybind for python, to run format + isort

This is great, thanks for sharing. I might steal it for documentation ;)

Related to this - it seems like the fixable list set in the config file also affects what shows up in the Quick Fix menu - is there a way to mark fixable/unfixable rules just for the ruff.executeAutoFix command but not for the Quick Fix menu?

No, currently there's no way to do that. Happy to discuss it in an issue at https://github.com/astral-sh/ruff-vscode

[aci-gbrandt]

I get the following warning in VSCode and have no idea how to fix it:

The legacy server (ruff-lsp) has been deprecated. The following settings were only supported by the legacy server and has been deprecated: ["ruff.showNotifications"]. Please migrate to the new settings or remove them. Feel free to comment on the GitHub discussion to ask questions or share feedback.

Can anybody point me in the right direction?

[aci-gbrandt]

I've never set that setting, I can't find it anywhere in my config files. I use pyproject.toml for all the ruff config

[dhruvmanila]

Oh interesting. Can you make sure and check all of your VS Code settings?

• User settings (aka global settings)
• Workspace settings
• If in a multi-root workspace, check the workspace folder settings

Additionally, if you're using the settings UI, can you try switching to the JSON view and check if ruff.showNotifications is present there:

[aci-gbrandt]

Found it in JSON mode, thanks.

[buhrmann]

Hi, could you perhaps share where you found it? I keep getting the same message and can't find the setting anywhere.

[dhruvmanila]

@buhrmann Hi, can you follow the steps I've mentioned in the above comment at #15991 (reply in thread) ? You'll need to look at the JSON settings.

[jtchen2k]

I prefer using single quotes in most of my projects, so I previously had this config in my VSCode settings.json:

  "ruff.format.args": [
      "--config",
      "format.quote-style='single'",
  ],

From what I understand, I now need to specify this setting in a separate toml file, using:

 "ruff.configuration": "~/.config/custom_ruff_config.toml"

While it works, it lacks the benefit of VSCode's settings synchronization, which allows me to conveniently write and format new Python scripts on different machines, on any workspace folders.

The document mentions that this change introduces "more granular settings", but to me, the original approach already felt quite granular. Would you consider adding a similar workaround to retain the previous feature? Or am I missing anything in the document?

[dhruvmanila]

Thank you for the feedback. You're correct that the current workaround is to implement a common config file that'll be used for options that are not available directly in the editor. We've gotten a lot of feedback around this and we've decided to dedicate some time to resolve this soon. This is being tracked here: astral-sh/ruff-vscode#6.

[T-256]

Could ruff.configuration support for remote url help this case?

[dhruvmanila]

Could ruff.configuration support for remote url help this case?

I'm not sure I follow. Do you mind expanding? Do you mean that the server fetches a config file from a URL where it's hosted?

[T-256]

Do you mean that the server fetches a config file from a URL where it's hosted?

Yes, via HTTP requests. When VSCode's settings synchronization happening, Config file will be available to every machine via internet.
I'm aware that it comes with some overheads like internet availability and validation, but just throw out my idea 🤷‍♂️

[dhruvmanila]

Thanks for sharing your idea. I think there's a request for something like that in the config file itself (can't find the issue) via extend (I think?). This would also add additional burden on the user to host their config file somewhere along with requirements that you've mentioned which is kind of similar to the existing problem in that the user needs to create a config file somewhere on the file system.

[ste-el-bow]

cannot migrate to native server, not sure why.
Here is the settings i have

    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
          "source.fixAll": "explicit",
          "source.organizeImports": "explicit"
        },
        "editor.defaultFormatter": "charliermarsh.ruff"
      },
      "ruff.configuration": "project/pyproject.toml",  
      "ruff.organizeImports": true,
      "ruff.lint.enable": true,
      "ruff.lint.args": ["--config=project/pyproject.toml"],
      "ruff.format.args": ["--config=projecti/pyproject.toml"],
      "ruff.configurationPreference": "filesystemFirst"

and it is fine, if i remove

      "ruff.lint.args": ["--config=project/pyproject.toml"],
      "ruff.format.args": ["--config=projecti/pyproject.toml"],

vscode is complaining about imports. I001 import block un-sorted or un-formatted.
isn't this line

            "ruff.configuration": "project/pyproject.toml",  

enough?

[MichaReiser]

It seems correct to me that you see I001 errors, considering that the rule is enabled. Or is it that you don't expect to see I001 errors because the imports are correctly sorted?

[ste-el-bow]

I don't expect to see them, they are not showing with old ruff-lsp, they are not on CI. but if i switch to native it is start showing and formats code differently makes my PRs failing at the ruff action. CI/local shares same .toml

[MichaReiser]

Can you try removing the ruff.configuration options. I wonder if it is even needed. This might otherwise be related to #15920

[ste-el-bow]

No real difference. What makes error gone are that two lines:

      "ruff.nativeServer": "off",
      "ruff.lint.args": ["--config=${workspaceFolder}/vms-core-api/pyproject.toml"],
      ```

[dhruvmanila]

I think we'll need a way to reproduce this.

From this thread, I only have the following project structure:

.
├── .vscode
│   └── settings.json
├── subfolder
│   ├── foo.py
│   └── pyproject.toml
└── test.py

where,

• The VS Code settings that you've provided are in a workspace folder (.vscode/settings.json)
• The config that you've provided are in subfolder/pyproject.toml

What we would additionally need is:

1. Source code which raises the diagnostic (just the imports section)
2. Where should we place the source code? Should it be in a file in the root directory or within subfolder/?
3. Do you have a config file in the root directory?
4. What is the version of ruff and the VS Code extension that you're using?

[CoreyMSchafer]

I really like only having my code checked as I save and not having it underlining things as I'm typing. Are there plans to implement an equivalent of "ruff.lint.run": "onSave"? I'm using VS Code. This would be a terrific feature. Or if there are ways to get the equivalent of this with the native server I would love to hear it. Thanks.

[dhruvmanila]

Thanks for the feedback.

To provide some context, I think the main reason that the onSave setting existed was to mitigate the performance issues for the legacy server (astral-sh/ruff-vscode#110) but the native server does not face this issue here which is why we decided not to add this feature.

Is it mainly around UX i.e., diagnostics highlighting via underlines? I'm curious to know if you're facing similar issues with other language server that you're using alongside Ruff? I'm not sure if there's a way to disable diagnostics rendering while typing in VS Code but if that is possible, it might help in your case.

I'm not opposed to adding this feature but I'd prefer to see if there are others who wants this as well.

[voetsjoeba]

Yes please. I dislike the squigglies freaking out while I'm still typing.

[suryastena]

Yes! This would be really useful - personally I find the diagnostics distracting while typing. I like way the rust/rust-analyzer extension for vscode works for example - that sort of 'diagnostics only on save' as an option would be really nice. Thanks!

[dhruvmanila]

Ref: #18912

[neutralino-ai]

Hi, it's not usable. check astral-sh/ruff-vscode#676
swithing "ruff.nativeServer" to "off" makes it usable temperarily.

[dhruvmanila]

Thanks for reporting, I've responded in the issue.

[dhruvmanila]

This is fixed.

[BaconPancakes]

Hey folks, monorepo user here.

I have settings that look like this

        "ruff.lint.args": [
            "--config=monorepo/settings/pyproject.toml",
            "--config=format={docstring-code-format=true}",
            "--config=lint.pydocstyle={convention='google'}",
            ]

Effectively, the team-level VSCode configuration file extends the global (monorepo level) config file. We prefer to avoid having a bunch of toml files lying around for every single tool, and we want to avoid a directory-level pyproject.toml because tools have been known to get confused about how to merge with the "global" pyproject.toml.

Is the only workaround right now to add a directory level ruff.toml that extends the global pyproject.toml? I see that there is some work on reproducing some of the config over to VSCode settings - will it be a 1 for 1 (or at least contain the ones we use above?)

[dhruvmanila]

Thank you @T-256 for providing some context.

In the future, we're thinking of splitting the ruff.configuration into ruff.configuration (strictly an object) and ruff.configurationFile to make it explicit and allow users to specify both.

Effectively, the team-level VSCode configuration file extends the global (monorepo level) config file. We prefer to avoid having a bunch of toml files lying around for every single tool, and we want to avoid a directory-level pyproject.toml because tools have been known to get confused about how to merge with the "global" pyproject.toml.

I think I'd want to better understand the use-case along with the project structure. Can you specify what does "team-level" and "global (monorepo level)" configuration file means? By extending, do you mean by using extend?

Regarding the settings that you've provided, are those specific to your needs i.e., as they're set in an editor context, they are expected to only affect your editing experience. I'm confused as to why is there a need to provide --config=monorepo/settings/pyproject.toml? Can that not be specified at the project level so that it affects everyone working on that project or is that already happening?

[BaconPancakes]

Yes, let me clarify.

We are a large organization comprising of many teams that all maintain a common repository ("monorepo"). The organization has specified a "global" pyproject.toml that contains and enforces organizational-level settings for linting, formatting, tooling etc.

Each team generally has a sub-project that lives in a subdirectory. Individual teams also have the flexibility to add some additional rules on top of the global configuration.

Now, the "global" rules are enforced by static tests. There is no organizational level "editor" settings, ie VSCode configurations. Our team uses a VSCode configuration to add some editor-time (language server) ruff checks on top of what is enforced by the global rules.

By extending, do you mean by using extend?

Yes, after reading the thread, I concluded that the extend setting could be used to satisfy our use case, at the cost of an extra configuration file.

Regarding the settings that you've provided, are those specific to your needs i.e., as they're set in an editor context, they are expected to only affect your editing experience. I'm confused as to why is there a need to provide --config=monorepo/settings/pyproject.toml? Can that not be specified at the project level so that it affects everyone working on that project or is that already happening?

The editor settings live in a .code-workspace file that is version controlled and shared among the team. It is however not generally used for the organization as a whole.

[dhruvmanila]

Thank you for providing all the details.

Yes, after reading the thread, I concluded that the extend setting could be used to satisfy our use case, at the cost of an extra configuration file.

Yeah, we recommend using extend especially for a monorepo setup.

If I understand correctly, the editor settings live in .code-workspace which will now be moved to a local ruff.toml file for your team which will extend the global config file. Is that correct? I think having an additional file has an advantage that it can be shared with non-VS Code users as well.

[T-256]

Yeah, we recommend using extend especially for a monorepo setup.

It isn't specified in docs, but IIUC, ruff cli currently accept and merge multiple --config path/to/file.toml. For consistency between server and cli, I recommend hint user to use extend option in one config file instead of passing multiple cli args of different files.
(Or the planned ruff.configurationFile settings could take array to for making consistency)

[dhruvmanila]

It isn't specified in docs, but IIUC, ruff cli currently accept and merge multiple --config path/to/file.toml. For consistency between server and cli, I recommend hint user to use extend option in one config file instead of passing multiple cli args of different files.

I think the reason that we merge --config options is because you can only provide a single key = value pair on the command-line, so if one needs to provide multiple options then they would need to use --config flag multiple times.

We haven't decided on the ruff.configurationFile setting yet and that will depend on user feedback. If the current ruff.configuration suffices the user needs, then I don't think we should provide an additional option. One advantage of providing ruff.configurationFile would be that the in-editor settings UI experience is better as the user can provide the file path directly in the UI as currently ruff.configuration can only be edited in the settings.json file.

[stinodego]

I would like to migrate to the native language server, but I have the following settings that prevent me from upgrading:

    "ruff.lint.args": [
        "--unfixable",
        "F841,F401,B007",
        "--unsafe-fixes"
    ],

It looks like the native language server does not support unsafe fixes, and also doesn't support marking specific lints as unfixable. Is that correct? If so, consider this a feature request for the native server to support this so that I can migrate!

I know I can set this in the ruff configuration file, but these are settings I want to use myself across all my projects and don't want to force upon colleagues that work on the same code base (which would be the case if I put it in the project's config file).

[T-256]

Related to #16296

[dhruvmanila]

I know I can set this in the ruff configuration file, but these are settings I want to use myself across all my projects and don't want to force upon colleagues that work on the same code base (which would be the case if I put it in the project's config file).

The way to solve this right now would to provide a configuration file path in ruff.configuration. The file would define an editor agnostic configuration that's specific to your needs in addition to the project requirements. This file could live outside the project like ~/editors/ruff.toml.

[stinodego]

The way to solve this right now would to provide a configuration file path in ruff.configuration. The file would define an editor agnostic configuration that's specific to your needs in addition to the project requirements. This file could live outside the project like ~/editors/ruff.toml.

This seems to work - thanks!

I was aware of the configuration option but it wasn't clear to me how my personal config would 'merge' with the individual project configs. But from initial testing it looks like it works as expected for my use case.

[dhruvmanila]

That's great to hear, thanks for the update.

Regardless, as mentioned, we're planning to expand ruff.configuration to provide the config directly (#16296).

[dipta007]

how to do in cursor ide?

[dhruvmanila]

Can you provide more details? What do you need help me? We've provided a migration guide and I think the migration in Cursor should be similar to VS Code.

[xerpi]

I'm using VSCode and even though I'm not setting any option to Ruff, I'm getting;

[warning] The following settings have been deprecated in the native server: 'ruff.format.args' in user settings. Please [migrate](https://docs.astral.sh/ruff/editors/migration/) to the new settings or remove them. Feel free to comment on the [GitHub discussion](https://github.com/astral-sh/ruff/discussions/15991) to ask questions or share feedback.

Any idea what could be setting ruff.format.args and why?

[MichaReiser]

It seems that you have some user settings for the ruff extension. Can you open your user settings Ctrl/Cmd+Shift+P -> Open User Settings (JSON) and then see if there are any settings starting with ruff.?

[dhruvmanila]

It could be related to astral-sh/ruff-vscode#491, the UI is a bit confusing for array like settings.

[xerpi]

@MichaReiser Thank you so much—that was it!
I had:

    "ruff.format.args": [
        "--line-length=100"
    ],

I grepped so many places for it, but in the end, it was just in the VSCode settings... 🤦‍♂️

[contang0]

Hi, I have 0 ruff-related options set in my settings.json or any of my pyproject.toml files and I keep getting this warning. My ruff version is up to date. How do I make it go away?

[contang0]

I do not have any. The only one that seemed related was "editor.defaultFormatter": "charliermarsh.ruff", but I commented it out before posting here and the warning was still popping up.

[contang0]

Here we go, it was picking up ruff installation from some venv, not from the base environment.

I only got this (much more useful) message when I switched to Native Server = True in the extension settings. I think this should be in the migration documentation.

[MichaReiser]

Oh nice. Yes, it would be great if the deprecation message could say that the extension used ruff-lsp because the ruff version is too old.

[dhruvmanila]

Yeah, I agree. Sorry for the churn.

[dhruvmanila]

Although we do log the message on the console i.e., in "Ruff: Show client logs", we just need to append it to the deprecation message.

[BugReporterNova]

Is there a command i can run to migrate? Something like

ruff --migrate C:/example/dir/my_file_name (optional extra args)

would be perfect. My apologies if this question was already asked and i skimmed over it.

[dhruvmanila]

No need to apologize for asking a valid question :)

There's no command as doing this in an automated way would be very complicated. I'm happy to help you migrate if you can provide me with your setup and VS Code settings. We also have a migration guide if that's helpful.

[BugReporterNova]

Thank you for the quick response and taking the time to help people like this. I'll first give it a proper go at understanding it myself. If I still have questions after that I'll reach out :)

[jenom]

I just to add the info that I got this error message:

The following settings have been deprecated in the native server: 'ruff.lint.run' in user settings. Please [migrate](https://docs.astral.sh/ruff/editors/migration/) to the new settings or remove them. Feel free to comment on the [GitHub discussion](https://github.com/astral-sh/ruff/discussions/15991) to ask questions or share feedback.

while the setting was actually in the remote settings.json. It took me quite some while to figure it out so I hope it helps others.

[dhruvmanila]

Thank you for sharing your experience.

[Poikilos]

I have absolutely 0 custom settings, but it still has a link to migration instructions and says

2025-03-18 18:12:51.084 [warning] The legacy server (ruff-lsp) has been deprecated. Stable version of the native server requires Ruff 0.5.3, but found 0.0.262 at /home/redacted/.local/bin/ruff instead. Please upgrade Ruff to use the native server; using the legacy server (ruff-lsp) for now. Feel free to comment on the GitHub discussion to ask questions or share feedback.
2025-03-18 18:12:51.084 [info] Resolved 'ruff.nativeServer: auto' to use the legacy (ruff-lsp) server
2025-03-18 18:12:51.108 [info] Server run command: python3 /home/redacted/.vscode/extensions/charliermarsh.ruff-2025.18.0-linux-x64/bundled/tool/server.py
2025-03-18 18:12:51.114 [info] Server: Start requested.
2025-03-18 18:14:25.435 [info] Name: Ruff
2025-03-18 18:14:25.435 [info] Module: ruff
2025-03-18 18:14:25.435 [info] Using interpreter: python3
2025-03-18 18:14:25.490 [info] Using the Ruff binary: /home/redacted/.local/bin/ruff
2025-03-18 18:14:25.497 [warning] The legacy server (ruff-lsp) has been deprecated. Stable version of the native server requires Ruff 0.5.3, but found 0.0.262 at /home/redacted/.local/bin/ruff instead. Please upgrade Ruff to use the native server; using the legacy server (ruff-lsp) for now. Feel free to comment on the GitHub discussion to ask questions or share feedback.
2025-03-18 18:14:25.497 [info] Resolved 'ruff.nativeServer: auto' to use the legacy (ruff-lsp) server
2025-03-18 18:14:25.501 [info] Server run command: python3 /home/redacted/.vscode/extensions/charliermarsh.ruff-2025.18.0-linux-x64/bundled/tool/server.py

Even if I uninstall and reinstall, the same occurs.

:edit: Also, the Migration Instructions do not say how to "Update the ruff version"

IMO it should just have a button to fix it, or fix the settings if I have no custom settings (as I stated, I'm using all defaults), as since it installed ruff, it should be able to upgrade it.

[dhruvmanila]

Thank you for the feedback.

It seems that you're using a pretty old Ruff version (0.0.262) as per the logs. The native server requires a more recent version as stated in the logs (>=0.5.3). Do you mind upgrading Ruff or is it not possible (maybe due to some company policy, etc.)?

:edit: Also, the Migration Instructions do not say how to "Update the ruff version"

I don't think we can provide that because we don't know how you installed Ruff in the first place and there are multiple ways to install it.

IMO it should just have a button to fix it, or fix the settings if I have no custom settings (as I stated, I'm using all defaults), as since it installed ruff, it should be able to upgrade it.

The extension doesn't install Ruff but it does include a bundled version of it which should be the latest version for you as you're on the latest extension version (2025.18.0) as per the logs.

The Ruff path as shown in the logs (~/.local/bin/ruff) means that you've installed Ruff manually which is what the extension used but as it's pretty old it's showing the warning.

Does this help?

[Poikilos]

If it is one of those methods, it must be curl -LsSf https://astral.sh/ruff/install.sh | sh because I have no package (It was not a symlink, but I also confirmed manually there was no apt, snap, nor pip package installed), and it is in .local which indicates it was installed manually at the user level. If I run the shell install again, now the aforementioned ruff executable is updated.

[dhruvmanila]

I'm not sure I follow here, is your issue resolved?

[Poikilos]

It is also happening on my Windows computer even when it says it (ruff extension version 2025.22.0) is using the bundled version:

2025-03-31 10:28:32.364 [info] Name: Ruff
2025-03-31 10:28:32.364 [info] Module: ruff
2025-03-31 10:28:32.364 [info] Python extension loading
2025-03-31 10:28:32.364 [info] Waiting for interpreter from python extension.
2025-03-31 10:28:32.364 [info] Python extension loaded
2025-03-31 10:28:32.364 [info] Using interpreter: c:\Users\redacted\git\python-openlcb\.venv\Scripts\python.exe
2025-03-31 10:28:32.984 [info] Falling back to bundled executable: c:\Users\redacted\.vscode\extensions\charliermarsh.ruff-2025.22.0-win32-x64\bundled\libs\bin\ruff.exe
2025-03-31 10:28:34.056 [warning] The legacy server ([ruff-lsp](https://github.com/astral-sh/ruff-lsp)) has been deprecated. The following settings were only supported by the legacy server and has been deprecated: 'ruff.lint.args' in workspace settings. Please [migrate](https://docs.astral.sh/ruff/editors/migration/) to the new settings or remove them. Feel free to comment on the [GitHub discussion](https://github.com/astral-sh/ruff/discussions/15991) to ask questions or share feedback.
2025-03-31 10:28:34.063 [info] Resolved 'ruff.nativeServer: auto' to use the legacy (ruff-lsp) server
2025-03-31 10:28:34.338 [info] Server run command: c:\Users\redacted\git\python-openlcb\.venv\Scripts\python.exe c:\Users\redacted\.vscode\extensions\charliermarsh.ruff-2025.22.0-win32-x64\bundled\tool\server.py
2025-03-31 10:28:34.340 [info] Server: Start requested.
2025-04-01 11:03:33.894 [info] Name: Ruff
2025-04-01 11:03:33.894 [info] Module: ruff
2025-04-01 11:03:33.894 [info] Python extension loading
2025-04-01 11:03:33.894 [info] Waiting for interpreter from python extension.
2025-04-01 11:03:33.894 [info] Python extension loaded
2025-04-01 11:03:33.894 [info] Using interpreter: c:\Users\redacted\git\python-openlcb\.venv\Scripts\python.exe
2025-04-01 11:03:34.753 [info] Falling back to bundled executable: c:\Users\redacted\.vscode\extensions\charliermarsh.ruff-2025.22.0-win32-x64\bundled\libs\bin\ruff.exe
2025-04-01 11:03:34.964 [warning] The legacy server ([ruff-lsp](https://github.com/astral-sh/ruff-lsp)) has been deprecated. The following settings were only supported by the legacy server and has been deprecated: 'ruff.lint.args' in workspace settings. Please [migrate](https://docs.astral.sh/ruff/editors/migration/) to the new settings or remove them. Feel free to comment on the [GitHub discussion](https://github.com/astral-sh/ruff/discussions/15991) to ask questions or share feedback.
2025-04-01 11:03:34.964 [info] Resolved 'ruff.nativeServer: auto' to use the legacy (ruff-lsp) server
2025-04-01 11:03:34.974 [info] Server run command: c:\Users\redacted\git\python-openlcb\.venv\Scripts\python.exe c:\Users\redacted\.vscode\extensions\charliermarsh.ruff-2025.22.0-win32-x64\bundled\tool\server.py
2025-04-01 11:03:34.976 [info] Server: Start requested.

[MichaReiser]

This does sound reasonable and would improve ergonomics. @dhruvmanila do you know if the editor can write user settings (at least in vs code)?

[Poikilos]

Maybe instead of a warning that jumps to the documentation, make a warning that jumps to the setting, and place a "Migrate" button on each deprecated setting?

• Regardless, the new setting is missing from the settings GUI and only "ruff.lint.ignore" is shown with a deprecation warning. So trying to use the settings panel will cause a regression of the user's fixes even if they migrate manually using documentation. All of the related new settings are not present, but instead there is an "Edit in settings.json" button which creates an empty string (which is not the right type [should be {}], and misleading):
  
  I hope adding the new settings to the GUI is planned, and that you will also consider migrate buttons.

Really, these settings need to be stored in the workspace somehow (or in other words, any scope, as managed by the settings system of VSCode) otherwise it isn't really integrated with VSCode. Isn't there any way to feed the settings to ruff when you call it? My project is for a company and we all need the same ignore settings for the specific project to be stored in git like we can with every other extension we use.

[dhruvmanila]

I don't think it's a simple conversion as you've suggested. The ruff.lint.args can contain any settings that can be specified on the command-line including the --config flag which will be very difficult to convert into the relevant new settings. We'd need to parse all the CLI flags that's possible under ruff check subcommand and special case --config flag. We'd need to detect whether --config is using a file path or a TOML setting and all of these would need to be done in the VS Code extension where we don't have the benefit of the schema that the Ruff binary has.

[dhruvmanila]

• All of the related new settings are not present, but instead there is an "Edit in settings.json" button which creates an empty string (which is not the right type even, and misleading):

I do understand that this is the downside of allowing arbitrary JSON object for ruff.configuration but unfortunately that is not in our control. VS Code cannot provide GUI interface for all type of settings.

An empty string is a valid type for ruff.configuration because it can accept a file path to the config file as well. Refer https://docs.astral.sh/ruff/editors/settings/#configuration.

One option that we've talked about before would be to split ruff.configuration into two settings: ruff.configurationFile and ruff.configuration so that the GUI settings can at least render ruff.configurationFile properly.

[Poikilos]

I don't think it's a simple conversion as you've suggested. The ruff.lint.args can contain any settings that can be specified on the command-line including the --config flag which will be very difficult to convert into the relevant new settings. We'd need to parse all the CLI flags that's possible under ruff check subcommand and special case --config flag. We'd need to detect whether --config is using a file path or a TOML setting and all of these would need to be done in the VS Code extension where we don't have the benefit of the schema that the Ruff binary has.

I hate to tell you, but the work you describe sounds completely reasonable and necessary (other than forking ruff-lsp to use the native server, which may even be better, but still need this work probably). Any extension should have awareness of the backend it uses, otherwise it is no longer a GUI following VS Code conventions (such as to allow configuration using whatever means it implements), but rather just a shim, and not significantly different than uninstalling the extension and adding a call to ruff itself to tasks.json (with a problemMatcher to detect the line number) or using CLI/scripts.

[EricDepagne]

I also see this warning, but only when using the remote-ssh extension.
I can't find any occurrence of ruff.showNotification anywhere in any of my configuration file, and I have set the nativeServer parameter to on for the extension and the workspace.
I have no idea in which file the ruff extension finds this deprecated parameter. Maybe that could be added to the warning message, to help us correct it and lower our frustration when the message appears, which is every single time I open my remote workspace!

[EricDepagne]

Well, of course, after having written the comment, I found the settings.json file that caused the error.
It was in ~/.vscode-server/data/Machine/ directory (not sure about the universality of the Machine part).
And in this directory was a settings.json file with the ruff.showNotification setting. Removing it solved the issue.
Still, I thingk that showing the file where the wrong setting is would have saved me a lot of time.

[dhruvmanila]

Apologies for the frustration that it caused but I don't think there's any VS Code API which provides us the path to settings.json file where a specific config is being set. We do, however, get the scope in which the config is set which we've added to the warning message.

[EricDepagne]

After seeing the file name, I realise that vscode reads all its configuration files and then presents to the extensions the configurations parameters it has read and then the extensions check them, but with no knowledge of their origin.
So, very frustrating, but there is nothing you could have done, so apologies for expressing my frustration like this, that was not helpful.

[dhruvmanila]

No worries, thank you for understanding.

[brad-phobos]

Native server raises an error "Ruff received invalid settings from the editor" when navigating into installed packages:

2025-04-23 11:17:15.804281841  WARN No settings available for file:///usr/local/lib/python3.12/site-packages/cv2/__init__.py - falling back to default settings
2025-04-23 11:17:15.804285127 ERROR Failed to load settings from `configuration`: error looking key 'workspaceFolder' up: environment variable not found

This loses the rules, and causes flickering and constant popups as it refreshes frequently.

ruff-lsp behaves much better with just a quiet warning.

[Warn  - 11:20:42 AM] Skipping standard library file: /usr/local/lib/python3.12/site-packages/cv2/__init__.py

[dhruvmanila]

This is being tracked at astral-sh/ruff-vscode#741.

[injust]

it will be archived with the release of Ruff 0.11

@dhruvmanila Should https://github.com/astral-sh/ruff-lsp be archived by now?

[amyreese]

Thank you for reminding us! 😅

[Boon-in-Oz]

At my company we use Perforce to distribute our source. Most of us use VS Code, with a ruff.toml file shared between the packages we develop, plus a ruff.toml in the base of some package folders that begins by pointing back to the main one like
extend = '../../ruff.toml'
We also use typically Windows junctions to map everything to the same directory on our C dirves because some of the tools we use are not happy with different file paths on different PCs.

With this setup (two ruff.tomls, and a VS Code workspace in a junctioned directory), Ruff's native server cannot read our ruff.toml.
Running Ruff in a command line works, but in VS Code it does not.

The only way I've been able to get the latest versions of Ruff to work correctly is to set
"ruff.nativeServer": "off",
in my workspace settings. But of course that's not going to work forever. Please help!

• I have a very similar problem with VS Code's Python extension and with ty. ty mostly works but F12 is broken, while in the Python extension I can use "python.locator": "js"
• I'm actually not sure if the two ruff.toml files setup contributes to the problem. I've just realized that the Ruff "Output" window in VS Code shows Ruff's configuration as empty regardless of what the configuration actually is. Now I have it working perfectly, and almost all the settings still read as null or empty lists.

[MichaReiser]

Thanks for the feedback Would you mind opening an issue wit some more details (what's the directory structure).

[Boon-in-Oz]

I dug into it more with an LLM agent doing the work, and eventually figured out this has nothing to do with junctions or nested ruff.toml files. The problem appears to occur in any Python files outside the workspace.

#27427 <- contains a simple repro