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.

I built Ruff to test a theory: that Python tooling could be much, much faster.
- The Ruff VS Code extension ships no linting logic; its entire job is deciding which ruff binary runs and when to restart it.
- Binary resolution is a five-step ladder whose third rung runs a Python script through the user's own interpreter to locate the Rust binary the extension already bundles.
- Restart requests are coalesced into a single queued follow-up so virtualenv switches and config edits cannot spawn zombie servers.
- The extension is a facade over two Python environment APIs, absorbing upstream event noise so downstream consumers see one stable change event.
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.
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.
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
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.
| Dimension | ruff-vscode (current) | ruff-lsp (predecessor) | Pylance / Pyright |
|---|---|---|---|
| What it does | Connects Ruff to VS Code | Same, older architecture | Type checking, IntelliSense |
| Server language | Rust (ruff server) | Python | TypeScript (Pylance) / Python (Pyright) |
| Ruff invocation | In-process server | Subprocess per request | N/A |
| Binary discovery | Five-step ladder | Simpler, PATH + Python env | N/A |
| Notebook support | Yes, incl. range formatting | Limited | Partial |
| Replaces | Flake8, Black, isort, pyupgrade | Same, via subprocess | No |
| Pairs with | Pylance / Pyright | Same | Ruff |
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.





