Add support for using uv as an alternative formatter backend #19665

zanieb · 2025-07-31T17:45:28Z

This adds a new backend: internal | uv option to the LSP FormatOptions allowing users to perform document and range formatting operations though uv. The idea here is to prototype a solution for users to transition to a uv format command without encountering version mismatches (and consequently, formatting differences) between the LSP's version of ruff and uv's version of ruff.

The primarily alternative to this would be to use uv to discover the ruff version used to start the LSP in the first place. However, this would increase the scope of a minimal uv format command beyond "run a formatter", and raise larger questions about how uv should be used to coordinate toolchain discovery. I think those are good things to explore, but I'm hesitant to let them block a uv format implementation. Another downside of using uv to discover ruff, is that it needs to be implemented outside the LSP; e.g., we'd need to change the instructions on how to run the LSP and implement it in each editor integration, like the VS Code plugin.

github-actions · 2025-07-31T18:10:59Z

`ruff-ecosystem` results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Formatter (stable)

✅ ecosystem check detected no format changes.

Formatter (preview)

✅ ecosystem check detected no format changes.

MichaReiser · 2025-08-01T15:59:24Z

crates/ruff_server/src/format.rs

+        // TODO(zanieb): We should consider returning this case to the caller somehow
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            tracing::warn!("uvx ruff format failed: {}", stderr);


We should probalby show a message to the user if that happens see Client

Can we differentiate between failures due to syntax errors in an easy way?

Will look at the Client for sending the message. Thank you!

See d23af97

My understanding is this will propagate upstream as the format_internal errors do. We could show a message directly to the user with more context, but I think we can defer that for now?

As a frontend to Ruff's formatter. There are some interesting choices here, some of which may just be temporary: 1. We pin a default version of Ruff, so `uv format` is stable for a given uv version 2. We install Ruff from GitHub instead of PyPI, which means we don't need a Python interpreter or environment 3. We do not read the Ruff version from the dependency tree See astral-sh/ruff#19665 for a prototype of the LSP integration.

zanieb · 2025-08-22T19:26:20Z

@dhruvmanila would you mind helping me ship this? I'm not sure what all needs to happen :)

dhruvmanila · 2025-08-25T08:35:58Z

would you mind helping me ship this? I'm not sure what all needs to happen :)

Sure! I'll look into this in a bit

zanieb · 2025-08-25T12:23:19Z

I'll look into the test failures.

dhruvmanila

Thanks!

I read the corresponding Notion document for this in which you've mentioned:

Micha and I talked quite a bit offline about the IDE experience, and there are a couple possible approaches that we can take to alleviate those problems.

~~Is there any mention of other approaches apart from the one that's implemented in this PR?~~ Nevermind, I see it in the PR description.

There are couple of follow-ups that would need to be done:

Updating the documentation to include the new option, this needs to be done manually for editor settings
Updating the VS Code extension to expose this option in VS Code settings and pass it to the server

Can you confirm whether this was tested in the editor? If so, which editor did you test this with, I can try it out in some other editor.

dhruvmanila · 2025-08-25T12:37:40Z

crates/ruff_server/src/format.rs

+        let line_width = FormatOptions::line_width(&self.options).value().to_string();
+        let indent_width = FormatOptions::indent_width(&self.options)


Should this use self.options.line_width() and self.options.indent_width() instead?

Yep, thanks!

crates/ruff_server/src/format.rs

dhruvmanila · 2025-08-25T12:44:56Z

crates/ruff_server/src/format.rs

+        command.arg("--config");
+        command.arg(format!(
+            "format.quote-style = '{}'",
+            self.options.quote_style().as_str()
+        ));
+


I'm a bit surprised that this works, is this equivalent to --config format.quote-style = 'single' (notice there are no quotes to the --config value):

$ ruff format --config format.quote-style = 'single' --diff isolated.py error: invalid value 'format.quote-style' for '--config <CONFIG_OPTION>' tip: A `--config` flag must either be a path to a `.toml` configuration file or a TOML `<KEY> = <VALUE>` pair overriding a specific configuration option For more information, try '--help'.

I think the entire value would need to be quoted, so the following should work:

$ ruff format --config "format.quote-style = 'single'" --diff isolated.py

Same goes for other --config flags.

When using Command::arg the outer quotes (") are implicit. Those outer quotes are being parsed by your shell into a single argument. I think providing them here would actually break things, as they'd be included in the value.

Ah I see, thanks for clarifying

dhruvmanila · 2025-08-25T12:50:14Z

crates/ruff_server/src/format.rs

+    ) -> Command {
+        // TODO(zanieb): We should probably check the uv version to make sure it supports
+        // `uv format` or add a special error message when the subcommand doesn't exist
+        let mut command = Command::new("uv");


This will always use the uv command that comes the earliest on PATH as seen from within the editor. Do you see any issues that could occur when doing so?

Yes. It could be the wrong version.

I don't think I expect multiple uv versions to be available on people's machines — and when it happens it's usually an accident. We can provide a way to set the uv path in the future though. We'll want it for other things.

Yeah, that makes sense

dhruvmanila · 2025-08-25T12:50:31Z

crates/ruff_server/src/format.rs

+        // TODO(zanieb): We should probably check the uv version to make sure it supports
+        // `uv format` or add a special error message when the subcommand doesn't exist


Yeah, we'd also need to provide a better error message when the uv command itself isn't available.

What were you thinking for that case?

Like, what the error message would be?

Yeah, but I just made a small improvement here for now.

dhruvmanila · 2025-08-25T12:53:19Z

crates/ruff_server/src/format.rs

+fn format_range_external(
+    document: &TextDocument,
+    source_type: PySourceType,
+    formatter_settings: &FormatterSettings,
+    range: TextRange,
+    path: &Path,
+) -> crate::Result<Option<PrintedRange>> {


Returning Result type here would mean that any errors resulted would be counted as internal server error and will be shown to the user. I think this is fine for now, but we might want to categorize a subset of them with better error message for example the TODO comment to check whether the subcommand is available or not.

That makes sense, thanks for clarifying!

dhruvmanila · 2025-08-25T13:09:50Z

crates/ruff_server/src/session/options.rs

 struct FormatOptions {
    preview: Option<bool>,
+    backend: Option<FormatBackend>,
 }


Including it directly in the format table might indicate that this is a stable option, I think there are two ways to communicate the experimental nature of this feature:

Make it explicit in the documentation

Include it under experimental.format.backend similar to ty's experimental namespace (https://docs.astral.sh/ty/reference/editor-settings/#experimental)

I don't have strong feelings. (2) seems nice but is weird to transition off of?

Thinking about this more, I think the current structure is fine (including it in the existing format namespace).

dhruvmanila · 2025-08-25T13:19:07Z

The primarily alternative to this would be to use uv to discover the ruff version used to start the LSP in the first place. However, this would increase the scope of a minimal uv format command beyond "run a formatter", and raise larger questions about how uv should be used to coordinate toolchain discovery. I think those are good things to explore, but I'm hesitant to let them block a uv format implementation. Another downside of using uv to discover ruff, is that it needs to be implemented outside the LSP; e.g., we'd need to change the instructions on how to run the LSP and implement it in each editor integration, like the VS Code plugin.

Does this mean something like uv server ?

Yeah, I think I'd be a bit hesitant to make the change as described here mainly because we only control the client side implementation for VS Code while for other editors we'd need to explicitly specify on how to start the server and what does it mean to start it from uv vs ruff.

zanieb · 2025-08-26T13:23:41Z

Does this mean something like uv server ?

Yeah, basically.

... while for other editors we'd need to explicitly specify on how to start the server and what does it mean to start it from uv vs ruff.

Yeah, this was the same concern Micha and I had.

zanieb · 2025-08-26T13:24:04Z

The test failures on Windows are due to concurrent-installs being unsafe in uv. I'll fix that upstream.

This PR adds the `ruff.format.backend` setting corresponding to astral-sh/ruff#19665 in Ruff.

…sh#19665) This adds a new `backend: internal | uv` option to the LSP `FormatOptions` allowing users to perform document and range formatting operations though uv. The idea here is to prototype a solution for users to transition to a `uv format` command without encountering version mismatches (and consequently, formatting differences) between the LSP's version of `ruff` and uv's version of `ruff`. The primarily alternative to this would be to use uv to discover the `ruff` version used to start the LSP in the first place. However, this would increase the scope of a minimal `uv format` command beyond "run a formatter", and raise larger questions about how uv should be used to coordinate toolchain discovery. I think those are good things to explore, but I'm hesitant to let them block a `uv format` implementation. Another downside of using uv to discover `ruff`, is that it needs to be implemented _outside_ the LSP; e.g., we'd need to change the instructions on how to run the LSP and implement it in each editor integration, like the VS Code plugin. --------- Co-authored-by: Dhruv Manilawala <[email protected]>

zanieb force-pushed the zb/format-uv branch from dc7d9b2 to 761b901 Compare July 31, 2025 17:59

Add support for using uv as an alternative formatter backend

9c62a4a

zanieb force-pushed the zb/format-uv branch from 761b901 to 9c62a4a Compare July 31, 2025 19:42

MichaReiser reviewed Aug 1, 2025

View reviewed changes

Improve error handling

d23af97

zanieb mentioned this pull request Aug 1, 2025

Add an experimental uv format command astral-sh/uv#15017

Merged

zanieb marked this pull request as ready for review August 22, 2025 19:26

Use uv format

479af03

Fix argument passing

eabb01c

dhruvmanila reviewed Aug 25, 2025

View reviewed changes

zanieb and others added 2 commits August 26, 2025 09:12

Review

175eb24

Add docs

b2e6c63

dhruvmanila mentioned this pull request Sep 8, 2025

Add ruff.format.backend setting astral-sh/ruff-vscode#832

Merged

dhruvmanila added configuration Related to settings and configuration server Related to the LSP server labels Sep 8, 2025

dhruvmanila approved these changes Sep 9, 2025

View reviewed changes

dhruvmanila merged commit 9cdac2d into main Sep 9, 2025
37 checks passed

dhruvmanila deleted the zb/format-uv branch September 9, 2025 15:09

dhruvmanila added a commit to astral-sh/ruff-vscode that referenced this pull request Sep 9, 2025

Add ruff.format.backend setting (#832)

e283ebb

This PR adds the `ruff.format.backend` setting corresponding to astral-sh/ruff#19665 in Ruff.

BrewTestBot mentioned this pull request Sep 10, 2025

ruff 0.13.0 Homebrew/homebrew-core#237206

Merged

		let line_width = FormatOptions::line_width(&self.options).value().to_string();
		let indent_width = FormatOptions::indent_width(&self.options)

		// TODO(zanieb): We should probably check the uv version to make sure it supports
		// `uv format` or add a special error message when the subcommand doesn't exist

Add support for using uv as an alternative formatter backend #19665

Add support for using uv as an alternative formatter backend #19665

Uh oh!

Conversation

zanieb commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ruff-ecosystem results

Linter (stable)

Linter (preview)

Formatter (stable)

Formatter (preview)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zanieb commented Aug 22, 2025

Uh oh!

dhruvmanila commented Aug 25, 2025

Uh oh!

zanieb commented Aug 25, 2025

Uh oh!

dhruvmanila left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zanieb Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dhruvmanila commented Aug 25, 2025

Uh oh!

zanieb commented Aug 26, 2025

Uh oh!

zanieb commented Aug 26, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

zanieb commented Jul 31, 2025 •

edited

Loading

github-actions bot commented Jul 31, 2025 •

edited

Loading

`ruff-ecosystem` results

dhruvmanila left a comment •

edited

Loading

zanieb Aug 26, 2025 •

edited

Loading