vllm-project/vllm · error · RuntimeError

Failed to find the NIXL wheel after building it.

Error message

Failed to find the NIXL wheel after building it.

What it means

The Ubuntu NIXL from-source installer builds a wheel with `pip wheel . --no-deps --wheel-dir=<tmp>` and then expects find_nixl_wheel_in_cache(temp_wheel_dir) to locate an nixl*.whl. If the build produced no (matching) wheel in the temp wheelhouse, this RuntimeError fires before the auditwheel repair step.

Source

Thrown at tools/install_nixl_from_source_ubuntu.py:201

    run_command(
        [
            sys.executable,
            "-m",
            "pip",
            "wheel",
            ".",
            "--no-deps",
            f"--wheel-dir={temp_wheel_dir}",
        ],
        cwd=os.path.abspath(NIXL_DIR),
        env=build_env,
    )

    # -- Step 3: Repair the wheel by copying UCX libraries --
    print("\n[3/3] Repairing NIXL wheel to include UCX libraries...", flush=True)
    unrepaired_wheel = find_nixl_wheel_in_cache(temp_wheel_dir)
    if not unrepaired_wheel:
        raise RuntimeError("Failed to find the NIXL wheel after building it.")

    # We tell auditwheel to ignore the plugin that mesonpy already handled.
    auditwheel_command = [
        "auditwheel",
        "repair",
        "--exclude",
        "libplugin_UCX.so",  # <-- Exclude because mesonpy already includes it
        unrepaired_wheel,
        f"--wheel-dir={WHEELS_CACHE_HOME}",
    ]
    run_command(auditwheel_command, env=build_env)

    # --- CLEANUP ---
    # No more temporary files to remove, just the temp wheelhouse
    run_command(["rm", "-rf", temp_wheel_dir])
    # --- END CLEANUP ---

    newly_built_wheel = find_nixl_wheel_in_cache(WHEELS_CACHE_HOME)

View on GitHub (pinned to c794754062)

Solutions

1. Re-run the script with output visible and check the `pip wheel` log above the failure for the real build error (usually meson/ninja/compiler missing).
2. Install build prerequisites: `apt install -y build-essential ninja-build` and `pip install meson meson-python ninja`.
3. Verify pip version and that no PIP_* env vars redirect wheel output, then re-run the installer.

Example fix

# before
python tools/install_nixl_from_source_ubuntu.py
# -> RuntimeError: Failed to find the NIXL wheel after building it.

# after
sudo apt install -y build-essential ninja-build
uv pip install meson meson-python ninja
python tools/install_nixl_from_source_ubuntu.py

# Pre-flight the build toolchain before invoking the installer
import shutil, sys
missing = [t for t in ("gcc", "ninja", "meson") if shutil.which(t) is None]
try:
    import mesonpy  # noqa: F401
except ImportError:
    missing.append("meson-python")
if missing:
    raise SystemExit(f"Missing build deps: {missing}; install before running installer")

try:
    subprocess.run([sys.executable, "tools/install_nixl_from_source_ubuntu.py"], check=True)
except subprocess.CalledProcessError:
    # inspect the pip wheel log; most common root cause is missing compiler/ninja/meson
    raise SystemExit("NIXL wheel build failed; install build-essential ninja-build meson meson-python and retry")

When it happens

Trigger: The `pip wheel` step failed silently or wrote its output elsewhere (PIP_WHEEL_DIR/builddir overrides), the meson build of NIXL failed leaving a partial artifact, or the produced wheel filename does not match the nixl wheel pattern find_nixl_wheel_in_cache expects.

Common situations: Missing build deps (meson/ninja, a C compiler) on the Ubuntu host; an old pip that ignores --wheel-dir semantics differently; a NIXL checkout whose project name/version produced an unexpectedly-named wheel; disk-full temp dirs.

Related errors

• Failed to find the repaired NIXL wheel.
• No precompiled vllm wheel found for architecture {arch} from
• Configuration error: {0}
• Endpoint not ready after {0}s: {1}
• Backend error: {0}

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/e8ffce3a89a58bac. Report an issue: GitHub.