{"record":{"id":"295545d13a89c81c","repo":"astral-sh/ruff","slug":"could-not-find-the-ruff-binary-in-any-of-the-follo","errorCode":null,"errorMessage":"Could not find the ruff binary in any of the following locations:\n{locations}\n","messagePattern":"Could not find the ruff binary in any of the following locations:\n(.+?)\n","errorType":"exception","errorClass":"RuffNotFound","httpStatus":null,"severity":"error","filePath":"python/ruff/_find_ruff.py","lineNumber":53,"sourceCode":"        # with module path `<target>/ruff`\n        _join(_matching_parents(_module_path(), \"ruff\"), \"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, ruff_exe)\n        if os.path.isfile(path):\n            return path\n\n    locations = \"\\n\".join(f\" - {target}\" for target in seen)\n    raise RuffNotFound(\n        f\"Could not find the ruff 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":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/astral-sh/ruff/blob/d1087a4b9e03d253a88703f34e0869ee4b805456/python/ruff/_find_ruff.py#L35-L71","documentation":"The ruff PyPI package is a thin Python wrapper around a prebuilt Rust executable. find_ruff_bin() in python/ruff/_find_ruff.py probes a fixed list of locations (the current Python's scripts dir, the base-prefix scripts dir, the bin directory above the site-packages/ruff package for --prefix and `uv run --with` installs, the bin dir adjacent to the package for pip install --target, and the user scheme scripts dir such as ~/.local/bin) for ruff(.exe). RuffNotFound is raised only when every candidate directory has been checked and none contains the binary; the message lists each location that was actually searched.","triggerScenarios":"Calling find_ruff_bin() (directly, or indirectly via `python -m ruff` or the generated Python API) when the ruff executable is absent from all probed directories: an sdist/source install that never shipped a binary, a wheel for a platform without prebuilt artifacts, a container image whose cleanup step deleted compiled files, or a pip install --target/--prefix layout where the sibling bin directory was not created.","commonSituations":"Docker multi-stage builds that strip site-packages; musl-based or exotic-architecture images where pip builds from source without placing the binary; mixing conda and pip environments; vendoring the ruff package without its bin directory; CI caching a broken wheel.","solutions":["Force-reinstall from a prebuilt wheel: pip install --force-reinstall --only-binary :all: ruff (or uv pip install --reinstall ruff).","Verify a wheel exists for your platform on PyPI; if not, switch base image/platform (e.g. manylinux instead of musl) or build the binary with cargo and put it on PATH.","If the binary exists elsewhere (vendored or moved), copy ruff(.exe) into one of the directories listed in the error message (e.g. the scripts dir or the bin directory next to the package).","Bypass the wrapper entirely and run the binary via uvx ruff or the standalone installer."],"exampleFix":"# before: source install without a platform wheel\npip install ruff --no-binary ruff\npython -m ruff --version   # RuffNotFound: binary missing from every searched location\n\n# after: install the platform wheel that bundles the executable\npip install --only-binary :all: --force-reinstall ruff\npython -m ruff --version   # ruff x.y.z","handlingStrategy":"try-catch","validationCode":"import sysconfig\nfrom pathlib import Path\n\n\ndef ruff_binary_available() -> bool:\n    try:\n        import ruff  # noqa: F401\n    except ImportError:\n        return False\n    exe = 'ruff' + (sysconfig.get_config_var('EXE') or '')\n    pkg_dir = Path(ruff.__file__).parent\n    candidates = [\n        sysconfig.get_path('scripts'),\n        sysconfig.get_path('scripts', vars={'base': sys.base_prefix}),\n        str(pkg_dir.parent / 'bin'),\n    ]\n    return any(p and Path(p, exe).is_file() for p in candidates)","typeGuard":null,"tryCatchPattern":"from ruff._find_ruff import RuffNotFound, find_ruff_bin\nimport shutil\n\ntry:\n    ruff_bin = find_ruff_bin()\nexcept RuffNotFound:\n    ruff_bin = shutil.which('ruff')  # fall back to a binary on PATH\n    if ruff_bin is None:\n        raise","preventionTips":["Pin ruff installs to prebuilt platform wheels (--only-binary :all:).","Add a post-install smoke test in Docker/CI: python -m ruff --version.","When vendoring with pip install --target, also copy the adjacent bin/ directory.","Prefer uvx ruff or the standalone installer where wheel installs are unreliable."],"tags":["python","pip","packaging","binary","installation","ruff"],"backgroundTag":"missing-packaged-binary","analyzedSha":"d1087a4b9e03d253a88703f34e0869ee4b805456","analyzedAt":"2026-08-20T16:33:49.445Z","contentChangedAt":"2026-08-20T16:33:49.445Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}