The Ruff VS Code Extension Is Not a Linter. It's a Binary Hunt.

Inside astral-sh/ruff-vscode, where five fallback strategies, a coalescing restart queue, and a Python helper script decide which ruff runs in your editor.

9 min read • View on GitHub • More from astral-sh

A wide, crosshatched editorial engraving of a workshop bench with four drawers. A human hand reaches past a drawer holding an unused iron key to select a Python-shaped tool from a second drawer, while a third drawer holds a small road symbol and a fourth sits empty. The scene visualizes the extension's core inversion: the bundled Rust binary is right there, and the hand ignores it in favor of asking the user's Python environment.
The extension often has the right ruff binary sitting in its own folder. It asks Python anyway.

I built Ruff to test a theory: that Python tooling could be much, much faster.

Charlie Marsh, Ruff creator and Astral founder · Announcing Astral, the company behind Ruff
Key Takeaways

The Extension Runs Python to Find a Rust Binary

The ruff-vscode extension ships a Python script. It lives at bundled/tool/find_ruff_binary_path.py. When the extension needs to know which ruff to run, it can execute that script through the user's own Python interpreter.

That is the whole inversion in one sentence. A VS Code extension for a Rust linter, distributed by Astral, runs Python to find itself. The ruff binary it is looking for is often already sitting in bundled/libs/bin/, right inside the extension folder.

So why ask Python at all? Because pyenv, asdf, and similar version shims only resolve correctly when they run in the workspace directory with the right interpreter. The extension can guess. The user's interpreter knows. Running the helper through that interpreter is the only way to see the same environment the user sees.

Everything else in the extension exists to answer the follow-up question: is this still the right binary?

Five Ways to Find ruff, Tried in Order

The resolution logic in common/server.ts is a five-step ladder. Each rung is a trust and reliability decision, not just a search.

Five ways to find ruff, tried in order. The third rung runs a Python helper through the user's interpreter, and it is the only rung a workspace-trust gate can disable.

Step one is explicit. If the user set ruff.path, the first valid entry wins. Nothing else gets a chance.

Step two is useBundled. If importStrategy is set to useBundled, the extension skips discovery entirely and runs the binary it shipped with.

Step three is the helper. The extension runs find_ruff_binary_path.py through the user's interpreter. This rung is the only one a workspace-trust gate can disable, because it executes code through the user's Python environment.

Step four is PATH. If the helper found nothing, the extension searches the system PATH.

Step five is the bundled binary as a last resort. If everything else failed, the extension falls back to what it shipped.

// Priority order for resolving the `ruff` binary:
// 1. Explicit `ruff.path` entries (first valid one wins)
// 2. Bundled binary, if `importStrategy` is `useBundled`
// 3. `find_ruff_binary_path.py`, run through the user's interpreter
// 4. `PATH` search
// 5. Bundled binary as a fallback

Two details make the ladder work in practice. Every subprocess call passes cwd so directory-sensitive shims resolve consistently at discovery, version check, and startup. And on Windows, .cmd and .bat paths are quoted and run through a shell, because batch files cannot execute through execFile otherwise.

How Ruff Ended Up Inside the Editor

Before ruff server existed, there was ruff-lsp. That was a Python-based language server that shelled out to the ruff command-line tool as a subprocess on every request. It worked, but it carried real costs.

Two version lines had to stay in sync. Every request paid subprocess startup. And features that depend on state across requests were hard to build.

That's where `ruff server` comes in: a language server written in Rust and built into Ruff.

Jane Lewis, Author of the Ruff v0.4.5 announcement · Ruff v0.4.5: Ruff's language server is now written in Rust
A WSJ hedcut-style editorial portrait of Charlie Marsh, Ruff creator and Astral founder, rendered in black ink on a pure white background with stipple shading for skin and fine hatching for hair.

Ruff 0.4.5 moved the language server into Ruff itself. ruff server is written in Rust and linked to the engine, so it can hold state across requests and avoid repeated process spawns.

The extension inherited its discovery logic from the ruff-lsp era. That is why a thin client carries so much environment code.

The Restart Queue Nobody Asked For

An extreme close-up editorial engraving of a single mechanical latch mounted on a horizontal queue rail. Three small tokens are stacked behind the latch, and two are merged into one as they pass through it. A thin taut thread runs from the latch to a second rail marked with a chain link, where a failed token has fallen off without blocking the token behind it. The image makes the extension's coalescing restart queue legible as a physical merge latch and a non-blocking chain.
Restart requests merge at the latch. A failed task falls off the chain without blocking the next one.

The extension has to restart ruff server whenever the world changes. A virtualenv switch. A Python extension install. A pyproject.toml save. An untrusted workspace becoming trusted. Each one is a restart trigger.

Users click fast. A restart can be in flight when the next trigger lands. Without coordination, you get zombie servers: two ruff processes fighting over the same workspace.

requestRestart coalesces them. If a restart is already running, a new request sets restartQueued = true and awaits the current promise instead of starting a second restart.

if (restartPromise) {
  restartQueued = true;
  await restartPromise;
  return;
}

restartPromise = (async () => {
  do {
    restartQueued = false;
    await doRestart();
  } while (restartQueued);
})().finally(() => {
  restartPromise = undefined;
});

The worker is a do...while loop. No matter how many requests arrive during a restart, at most one follow-up runs. And finally clears restartPromise, so a failure cannot leave the queue permanently stuck.

Environment changes get their own serialization. Each task is chained onto the previous one with .then(task, task). Passing the task as its own rejection handler means a failed earlier task does not block the tasks behind it. Errors get logged and swallowed in the chain while still propagating to the caller.

A Facade Over Two Python Extension APIs

The extension needs to know which Python environment is active. There are two ways to ask: @vscode/python-environments, the newer dedicated API, and @vscode/python-extension, the classic one.

getEnvironmentProvider() prefers the newer API and falls back to the classic one with a ?? chain. Two classes implement one interface: initialize, resolveInterpreter(path), and getActiveEnvironment(uri?).

The facade absorbs a lot of upstream noise. The newer extension emits duplicate change events, so the adapter caches per scope and forwards only real changes. It also activates the extension on demand and handles the case where python.useEnvironmentsExtension is false, which leaves extension.exports null.

Both backends bridge their events into one module-level EventEmitter. Downstream consumers subscribe to a single stable event regardless of which backend is active. The cost is doubled surface area that can drift. The benefit is that the rest of the extension never sees the difference.

What It Actually Is (And Isn't)

The extension is not a type checker. It is not a completion engine. It does not replace Pylance or Pyright. It connects Ruff's linting, formatting, and import organization to VS Code, then gets out of the way.

Dimensionruff-vscode (current)ruff-lsp (predecessor)Pylance / Pyright
What it doesConnects Ruff to VS CodeSame, older architectureType checking, IntelliSense
Server languageRust (ruff server)PythonTypeScript (Pylance) / Python (Pyright)
Ruff invocationIn-process serverSubprocess per requestN/A
Binary discoveryFive-step ladderSimpler, PATH + Python envN/A
Notebook supportYes, incl. range formattingLimitedPartial
ReplacesFlake8, Black, isort, pyupgradeSame, via subprocessNo
Pairs withPylance / PyrightSameRuff

The cleanest way to think about it: Ruff handles lint and format, a type checker handles types, and the extension handles the plumbing between Ruff and the editor. Most Python setups want all three.

Thin Clients Are Not Thin

The Ruff extension looks like a thin client. The interesting code says otherwise. The linting lives in a Rust binary. The extension's real product is lifecycle correctness under churn: finding the right binary, keeping it running, and restarting it at the right moments without spawning duplicates.

This is where editor tooling complexity actually lives. Not in features, which are usually delegated to a server. In discovery, trust, and environment churn. The next time an extension feels like magic, look at how much code exists just to decide which process to start.