{"record":{"id":"74bb32f18c5ae3a5","repo":"astral-sh/uv","slug":"could-not-find-the-uv-binary-in-any-of-the-followi","errorCode":null,"errorMessage":"Could not find the uv binary in any of the following locations:\n{locations}\n","messagePattern":"Could not find the uv binary in any of the following locations:\n(.+?)\n","errorType":"exception","errorClass":"UvNotFound","httpStatus":null,"severity":"error","filePath":"python/uv/_find_uv.py","lineNumber":50,"sourceCode":"        # with module path `<target>/uv`\n        _join(_matching_parents(_module_path(), \"uv\"), \"bin\"),\n        # The user scheme scripts directory, e.g., `~/.local/bin`\n        sysconfig.get_path(\"scripts\", scheme=_user_scheme()),\n    ]\n\n    seen = []\n    for target in targets:\n        if not target:\n            continue\n        if target in seen:\n            continue\n        seen.append(target)\n        path = os.path.join(target, uv_exe)\n        if os.path.isfile(path):\n            return path\n\n    locations = \"\\n\".join(f\" - {target}\" for target in seen)\n    raise UvNotFound(\n        f\"Could not find the uv binary in any of the following locations:\\n{locations}\\n\"\n    )\n\n\ndef _module_path() -> str | None:\n    path = os.path.dirname(__file__)\n    return path\n\n\ndef _matching_parents(path: str | None, match: str) -> str | None:\n    \"\"\"\n    Return the parent directory of `path` after trimming a `match` from the end.\n    The match is expected to contain `/` as a path separator, while the `path`\n    is expected to use the platform's path separator (e.g., `os.sep`). The path\n    components are compared case-insensitively and a `*` wildcard can be used\n    in the `match`.\n    \"\"\"\n    from fnmatch import fnmatch","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/astral-sh/uv/blob/f1a42680ff5272232d65748acf338b19778dde24/python/uv/_find_uv.py#L32-L68","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reinstall the wheel so module and binary stay together: `python -m pip install --force-reinstall --no-cache-dir uv`.","Use the official standalone installer (astral.sh/uv) or `uv self update` instead of distro repackaging that strips the executable.","For `--target`/`--prefix` layouts, verify `<target>/bin/uv` or `<prefix>/bin/uv` exists; the message lists the exact paths it probed.","If you invoke uv anyway, fall back to `shutil.which(\"uv\")` or the documented system location when `find_uv_bin()` raises."],"exampleFix":"# before\nfrom uv import find_uv_bin\nuv_bin = find_uv_bin()  # UvNotFound\n\n# after\nimport shutil\nfrom uv import find_uv_bin, UvNotFound\ntry:\n    uv_bin = find_uv_bin()\nexcept UvNotFound:\n    uv_bin = shutil.which(\"uv\")\n    if uv_bin is None:\n        raise","handlingStrategy":"try-catch","validationCode":"import os, sysconfig, uv  # package 'uv'\n\ncandidates = [\n    sysconfig.get_path(\"scripts\"),\n    os.path.join(os.path.dirname(uv.__file__), \"..\", \"..\", \"bin\", \"uv\"),\n]\nif not any(os.path.isfile(os.path.abspath(c)) for c in candidates if c):\n    raise SystemExit(\"uv executable missing next to the 'uv' package; reinstall the uv wheel\")","typeGuard":null,"tryCatchPattern":"import shutil\nfrom uv import find_uv_bin, UvNotFound  # UvNotFound subclasses FileNotFoundError\n\ntry:\n    uv_bin = find_uv_bin()\nexcept UvNotFound:\n    uv_bin = shutil.which(\"uv\")\nif uv_bin is None:\n    raise SystemExit(\"uv executable not found: reinstall uv (pip install --force-reinstall uv)\")","preventionTips":["Always install the uv package from its official wheel (`pip install uv`); source/distro repackaging may drop the bundled executable.","Smoke-test after install: `python -c \"from uv import find_uv_bin; print(find_uv_bin())\"`.","Keep the module and binary from the same install; do not mix a copied site-packages with a separately installed binary."],"tags":["packaging","pypi","binary","environment","filenotfound"],"backgroundTag":null,"analyzedSha":"f1a42680ff5272232d65748acf338b19778dde24","analyzedAt":"2026-08-16T04:51:47.599Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}