astral-sh/ruff · error

uv was not found; is it installed and on the PATH?

Error message

uv was not found; is it installed and on the PATH?

What it means

The Ruff language server delegates `uv format` for document/range formatting by spawning a `uv` subprocess. If spawning fails with `ErrorKind::NotFound`, the server bails with this anyhow error explaining that `uv` is not installed or not on the PATH.

Source

Thrown at crates/ruff_server/src/format.rs:315

        command.stdout(Stdio::piped());
        command.stderr(Stdio::piped());

        command
    }

    /// Execute the format command on the given source.
    fn format(
        &self,
        source: &str,
        path: &Path,
        range_with_index: Option<(TextRange, &LineIndex)>,
    ) -> crate::Result<FormatResult> {
        let mut command =
            self.build_command(path, range_with_index.map(|(r, idx)| (r, idx, source)));
        let mut child = match command.spawn() {
            Ok(child) => child,
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
                anyhow::bail!("uv was not found; is it installed and on the PATH?")
            }
            Err(err) => return Err(err).context("Failed to spawn uv"),
        };

        let mut stdin = child
            .stdin
            .take()
            .context("Failed to get stdin from format subprocess")?;
        stdin
            .write_all(source.as_bytes())
            .context("Failed to write to stdin")?;
        drop(stdin);

        let result = child
            .wait_with_output()
            .context("Failed to get output from format subprocess")?;

        if !result.status.success() {

View on GitHub (pinned to 26f38c119c)

Solutions

1. Install uv (e.g. `curl -LsSf https://astral.sh/uv/install.sh | sh` or `pip install uv`)
2. Verify with `which uv` / `where uv` that uv resolves on the PATH of the process that launched the editor
3. Configure the server's environment (e.g. `ruff.server.environment` or launcher env) to include uv's bin directory, then restart the editor

Example fix

# before (uv not on PATH)
# $ which uv
# uv not found
# after
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"  # then restart the editor

import shutil
if shutil.which('uv') is None:
    raise SystemExit("uv was not found; install it or add it to PATH before using LSP formatting")

When it happens

Trigger: Triggering format-on-save or a manual `textDocument/formatting`/`rangeFormatting` request while the `uv` executable cannot be found on the system PATH used by the server process.

Common situations: uv not installed at all; uv installed via a tool manager (e.g. pipx, cargo) whose bin dir isn't on the server's PATH; launching the editor from a GUI where PATH differs from the shell; wrong interpreter/environment for the LSP process.

Related errors

• The installed version of uv does not support `uv format`; up
• Failed to format document: {stderr}
• InternalError
• NotFound
• Notebook document expected from notebook source kind

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/ad2ac54bd732da0b. Report an issue: GitHub.