astral-sh/uv · error · UvNotFound

Could not find the uv binary in any of the following locatio

Error message

Could not find the uv binary in any of the following locations:
{locations}

What it means

`uv.find_uv_bin()` (from the `uv` PyPI package) locates the bundled executable by checking, in order: the current interpreter's scripts dir, the base-prefix scripts dir, the bin dir above a `lib/python*/site-packages/uv` (or Windows `Scripts` above `Lib/site-packages/uv`) module path, the bin dir adjacent to a `pip install --target` layout, and the user scheme scripts dir. If no `uv<EXE>` file exists in any of them it raises `UvNotFound` (a `FileNotFoundError` subclass) listing every location searched.

Source

Thrown at python/uv/_find_uv.py:50

        # with module path `<target>/uv`
        _join(_matching_parents(_module_path(), "uv"), "bin"),
        # The user scheme scripts directory, e.g., `~/.local/bin`
        sysconfig.get_path("scripts", scheme=_user_scheme()),
    ]

    seen = []
    for target in targets:
        if not target:
            continue
        if target in seen:
            continue
        seen.append(target)
        path = os.path.join(target, uv_exe)
        if os.path.isfile(path):
            return path

    locations = "\n".join(f" - {target}" for target in seen)
    raise UvNotFound(
        f"Could not find the uv binary in any of the following locations:\n{locations}\n"
    )


def _module_path() -> str | None:
    path = os.path.dirname(__file__)
    return path


def _matching_parents(path: str | None, match: str) -> str | None:
    """
    Return the parent directory of `path` after trimming a `match` from the end.
    The match is expected to contain `/` as a path separator, while the `path`
    is expected to use the platform's path separator (e.g., `os.sep`). The path
    components are compared case-insensitively and a `*` wildcard can be used
    in the `match`.
    """
    from fnmatch import fnmatch

View on GitHub (pinned to f1a42680ff)

Solutions

1. Reinstall the wheel so module and binary stay together: `python -m pip install --force-reinstall --no-cache-dir uv`.
2. Use the official standalone installer (astral.sh/uv) or `uv self update` instead of distro repackaging that strips the executable.
3. For `--target`/`--prefix` layouts, verify `<target>/bin/uv` or `<prefix>/bin/uv` exists; the message lists the exact paths it probed.
4. If you invoke uv anyway, fall back to `shutil.which("uv")` or the documented system location when `find_uv_bin()` raises.

Example fix

# before
from uv import find_uv_bin
uv_bin = find_uv_bin()  # UvNotFound

# after
import shutil
from uv import find_uv_bin, UvNotFound
try:
    uv_bin = find_uv_bin()
except UvNotFound:
    uv_bin = shutil.which("uv")
    if uv_bin is None:
        raise

import os, sysconfig, uv  # package 'uv'

candidates = [
    sysconfig.get_path("scripts"),
    os.path.join(os.path.dirname(uv.__file__), "..", "..", "bin", "uv"),
]
if not any(os.path.isfile(os.path.abspath(c)) for c in candidates if c):
    raise SystemExit("uv executable missing next to the 'uv' package; reinstall the uv wheel")

import shutil
from uv import find_uv_bin, UvNotFound  # UvNotFound subclasses FileNotFoundError

try:
    uv_bin = find_uv_bin()
except UvNotFound:
    uv_bin = shutil.which("uv")
if uv_bin is None:
    raise SystemExit("uv executable not found: reinstall uv (pip install --force-reinstall uv)")

When it happens

Trigger: Calling `from uv import find_uv_bin; find_uv_bin()` after the `uv` wheel's executable was not installed alongside the module: source installs, repackaged/distro builds that drop the binary, `pip install --target` into a nonstandard layout, `pip install --prefix` where the bin dir does not match the searched patterns, or environments (NixOS) that patch out prebuilt binaries.

Common situations: Tools that bootstrap uv through its Python package (`subprocess.run([find_uv_bin(), ...])`), Docker images that `pip install uv` into odd prefixes, CI caching a site-packages copy without the scripts dir, or a venv that has the `uv` module visible but was created before/without the executable.

Related errors

• {uv_bin_name} was not properly installed
• Using `uv.{attr_name}` is not allowed; build backend functio
• Extra names must start and end with a letter or digit and ma

AI-assisted analysis of astral-sh/uv@f1a42680ff (2026-08-16). Data as JSON: /api/errors/74bb32f18c5ae3a5. Report an issue: GitHub.