vllm-project/vllm · error · ValueError

No precompiled vllm wheel found for architecture {arch} from

Error message

No precompiled vllm wheel found for architecture {arch} from repo {repo_url}. All available wheels: {wheels}

What it means

Thrown during a VLLM_USE_PRECOMPILED=1 build when setup.py scans the nightly wheel repo's metadata.json and finds no entry whose package_name is 'vllm' and whose platform_tag contains the host's platform.machine() (e.g. x86_64, aarch64). The build therefore cannot locate a precompiled wheel to extract compiled extensions from. The full candidate list is included in the message so you can see what the repo actually published.

Source

Thrown at setup.py:978

    "path": "../vllm-0.11.2.dev278%2Bgdbc3d9991-cp38-abi3-manylinux1_x86_64.whl"
    },
    ...]"""
            from urllib.parse import urljoin

            for wheel in wheels:
                # TODO: maybe check more compatibility later? (python_tag, abi_tag, etc)
                if wheel.get("package_name") == "vllm" and arch in wheel.get(
                    "platform_tag", ""
                ):
                    print(f"Found precompiled wheel metadata: {wheel}")
                    if "path" not in wheel:
                        raise ValueError(f"Wheel metadata missing path: {wheel}")
                    wheel_url = urljoin(repo_url, wheel["path"])
                    download_filename = wheel.get("filename")
                    print(f"Using precompiled wheel URL: {wheel_url}")
                    break
            else:
                raise ValueError(
                    f"No precompiled vllm wheel found for architecture {arch} "
                    f"from repo {repo_url}. All available wheels: {wheels}"
                )

        return wheel_url, download_filename

    @staticmethod
    def extract_precompiled_and_patch_package(
        wheel_url_or_path: str,
        download_filename: str | None,
        *,
        extract_extensions: bool,
        extract_rust_frontend: bool,
    ) -> dict:
        import tempfile
        import zipfile

        temp_dir = None

View on GitHub (pinned to c794754062)

Solutions

Set VLLM_PRECOMPILED_WHEEL_LOCATION to a direct URL or local path of a wheel that matches your architecture (it short-circuits the repo lookup entirely).
Inspect the 'All available wheels' list in the message; if a wheel for another variant matches your arch, set VLLM_PRECOMPILED_WHEEL_VARIANT accordingly.
Point VLLM_PRECOMPILED_WHEEL_COMMIT at a commit known to have artifacts for your arch (check the nightly wheel repo index).
Drop VLLM_USE_PRECOMPILED and compile the CUDA/C++ extensions locally with `uv pip install -e . --torch-backend=auto`.

Example fix

# before
VLLM_USE_PRECOMPILED=1 uv pip install -e .
# -> ValueError: No precompiled vllm wheel found for architecture aarch64 ...

# after (point directly at an arch-matching wheel)
export VLLM_PRECOMPILED_WHEEL_LOCATION=https://wheels.vllm.ai/vllm-0.11.2.dev278-cp38-abi3-manylinux1_aarch64.whl
VLLM_USE_PRECOMPILED=1 uv pip install -e .

Defensive patterns

Strategy: validation

Validate before calling

# Before building: confirm a wheel exists for this arch in the nightly index
import json, platform, urllib.request

meta_url = "https://wheels.vllm.ai/nightly/metadata.json"  # or your repo's index
wheels = json.load(urllib.request.urlopen(meta_url))
arch = platform.machine()
ok = any(w.get("package_name") == "vllm" and arch in w.get("platform_tag", "") for w in wheels)
if not ok:
    raise SystemExit(f"No {arch} wheel published; set VLLM_PRECOMPILED_WHEEL_LOCATION or build from source")

Try / catch

try:
    subprocess.run(["uv", "pip", "install", "-e", "."], env=build_env, check=True)
except subprocess.CalledProcessError as e:
    if "No precompiled vllm wheel found" in (e.stdout or "") + (e.stderr or ""):
        # fall back to full source build without VLLM_USE_PRECOMPILED
        build_env.pop("VLLM_USE_PRECOMPILED", None)
        subprocess.run(["uv", "pip", "install", "-e", "."], env=build_env, check=True)
    else:
        raise

Prevention

Pre-check the nightly wheel index for your platform.machine() before starting a VLLM_USE_PRECOMPILED build.
Pin VLLM_PRECOMPILED_WHEEL_LOCATION to a known-good wheel URL in CI instead of relying on repo discovery.
On non-x86_64 builders, default to full source compilation rather than the precompiled path.

When it happens

Trigger: Running `VLLM_USE_PRECOMPILED=1 uv pip install -e .` on an architecture with no published nightly wheel (e.g. aarch64/s390x when only x86_64 manylinux wheels exist), or with VLLM_PRECOMPILED_WHEEL_COMMIT/VARIANT pointing at a commit/variant whose metadata.json has no wheel for your arch.

Common situations: Building vLLM from source on ARM servers or containers (e.g. Apple Silicon Docker, Graviton CI runners) with the precompiled shortcut; pinning a VLLM_PRECOMPILED_WHEEL_COMMIT whose nightly artifacts are incomplete; a nightly repo index that only published cu12 x86_64 wheels.

Related errors

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