{"record":{"id":"e8ffce3a89a58bac","repo":"vllm-project/vllm","slug":"failed-to-find-the-nixl-wheel-after-building-it","errorCode":null,"errorMessage":"Failed to find the NIXL wheel after building it.","messagePattern":"Failed to find the NIXL wheel after building it\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"tools/install_nixl_from_source_ubuntu.py","lineNumber":201,"sourceCode":"    run_command(\n        [\n            sys.executable,\n            \"-m\",\n            \"pip\",\n            \"wheel\",\n            \".\",\n            \"--no-deps\",\n            f\"--wheel-dir={temp_wheel_dir}\",\n        ],\n        cwd=os.path.abspath(NIXL_DIR),\n        env=build_env,\n    )\n\n    # -- Step 3: Repair the wheel by copying UCX libraries --\n    print(\"\\n[3/3] Repairing NIXL wheel to include UCX libraries...\", flush=True)\n    unrepaired_wheel = find_nixl_wheel_in_cache(temp_wheel_dir)\n    if not unrepaired_wheel:\n        raise RuntimeError(\"Failed to find the NIXL wheel after building it.\")\n\n    # We tell auditwheel to ignore the plugin that mesonpy already handled.\n    auditwheel_command = [\n        \"auditwheel\",\n        \"repair\",\n        \"--exclude\",\n        \"libplugin_UCX.so\",  # <-- Exclude because mesonpy already includes it\n        unrepaired_wheel,\n        f\"--wheel-dir={WHEELS_CACHE_HOME}\",\n    ]\n    run_command(auditwheel_command, env=build_env)\n\n    # --- CLEANUP ---\n    # No more temporary files to remove, just the temp wheelhouse\n    run_command([\"rm\", \"-rf\", temp_wheel_dir])\n    # --- END CLEANUP ---\n\n    newly_built_wheel = find_nixl_wheel_in_cache(WHEELS_CACHE_HOME)","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/tools/install_nixl_from_source_ubuntu.py#L183-L219","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Install build prerequisites: `apt install -y build-essential ninja-build` and `pip install meson meson-python ninja`.","Verify pip version and that no PIP_* env vars redirect wheel output, then re-run the installer."],"exampleFix":"# before\npython tools/install_nixl_from_source_ubuntu.py\n# -> RuntimeError: Failed to find the NIXL wheel after building it.\n\n# after\nsudo apt install -y build-essential ninja-build\nuv pip install meson meson-python ninja\npython tools/install_nixl_from_source_ubuntu.py","handlingStrategy":"try-catch","validationCode":"# Pre-flight the build toolchain before invoking the installer\nimport shutil, sys\nmissing = [t for t in (\"gcc\", \"ninja\", \"meson\") if shutil.which(t) is None]\ntry:\n    import mesonpy  # noqa: F401\nexcept ImportError:\n    missing.append(\"meson-python\")\nif missing:\n    raise SystemExit(f\"Missing build deps: {missing}; install before running installer\")","typeGuard":null,"tryCatchPattern":"try:\n    subprocess.run([sys.executable, \"tools/install_nixl_from_source_ubuntu.py\"], check=True)\nexcept subprocess.CalledProcessError:\n    # inspect the pip wheel log; most common root cause is missing compiler/ninja/meson\n    raise SystemExit(\"NIXL wheel build failed; install build-essential ninja-build meson meson-python and retry\")","preventionTips":["Install build-essential, ninja-build, meson, and meson-python before running the installer.","Run the installer from a writable shell so the `pip wheel` log is visible when it fails.","Keep pip current and clear PIP_WHEEL_DIR-style env overrides."],"tags":["nixl","build","wheels","ubuntu","tooling"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}