What causes "Unknown runtime environment" in vllm-project/vllm?

Set VLLM_TARGET_DEVICE explicitly for the device class you intend (e.g. `export VLLM_TARGET_DEVICE=cpu`) so classification succeeds.

vllm-project/vllm · error · RuntimeError

Unknown runtime environment

Error message

Unknown runtime environment

What it means

get_vllm_version() appends a local-version suffix (+cu, +rocm, +tpu, +cpu, +xpu) by classifying the build machine through _is_cuda()/_is_hip()/_is_tpu()/_is_cpu()/_is_xpu(). If none of the probes match, the environment is unrecognized and the RuntimeError aborts the version computation during setup.py execution.

Source

Thrown at setup.py:1295

                # skip this for source tarball, required for pypi
                if "sdist" not in sys.argv:
                    version += f"{sep}cu{cuda_version_str}"
    elif _is_hip():
        # Get the Rocm Version
        rocm_version = get_rocm_version() or torch.version.hip
        if rocm_version and rocm_version != envs.VLLM_MAIN_CUDA_VERSION:
            version += f"{sep}rocm{rocm_version.replace('.', '')[:3]}"
    elif _is_tpu():
        version += f"{sep}tpu"
    elif _is_cpu():
        # Check the local VLLM_TARGET_DEVICE (may be set by auto-detect above),
        # not envs.VLLM_TARGET_DEVICE, so CPU-only hosts still get `+cpu`.
        if VLLM_TARGET_DEVICE == "cpu":
            version += f"{sep}cpu"
    elif _is_xpu():
        version += f"{sep}xpu"
    else:
        raise RuntimeError("Unknown runtime environment")

    return version


def get_requirements() -> list[str]:
    """Get Python package dependencies from requirements.txt."""
    requirements_dir = ROOT_DIR / "requirements"

    def _read_requirements(filename: str) -> list[str]:
        with open(requirements_dir / filename) as f:
            requirements = f.read().strip().split("\n")
        resolved_requirements = []
        for line in requirements:
            if line.startswith("-r "):
                resolved_requirements += _read_requirements(line.split()[1])
            elif (
                not line.startswith("--")
                and not line.startswith("#")

View on GitHub (pinned to c794754062)

Solutions

Set VLLM_TARGET_DEVICE explicitly for the device class you intend (e.g. `export VLLM_TARGET_DEVICE=cpu`) so classification succeeds.
Build inside a supported Linux environment with torch installed (CUDA hosts: torch with a CUDA runtime and nvidia-smi on PATH).
Verify you are on a supported platform per docs (Linux x86_64 with CUDA/ROCm, TPU, CPU, or Intel XPU); macOS/Windows source builds are unsupported.

Example fix

# before
uv pip install -e .
# -> RuntimeError: Unknown runtime environment

# after
export VLLM_TARGET_DEVICE=cpu
uv pip install -e .

Defensive patterns

Strategy: validation

Validate before calling

# Before running setup.py, verify the environment classifies
import os, sys
if sys.platform not in ("linux", "linux2"):
    raise SystemExit("vLLM builds require Linux; use a Linux container")
os.environ.setdefault("VLLM_TARGET_DEVICE", "cpu")  # explicit beats auto-detect

Prevention

Always export VLLM_TARGET_DEVICE in build scripts so classification never depends on probes.
Run builds inside the documented Linux environment with torch preinstalled.
Never attempt setup.py on macOS/Windows hosts.

When it happens

Trigger: Running setup.py (`uv pip install -e .` or `python setup.py develop`) on a platform outside CUDA/ROCm/TPU/CPU/XPU support, or on a supported OS where device auto-detection fails to classify (e.g. detection helpers raise or return falsy for every category).

Common situations: Attempting to build vLLM on macOS or Windows; a Linux container where torch is absent, nvidia-smi is missing, and VLLM_TARGET_DEVICE is unset so auto-detect cannot classify the host; stale forks where a new hardware backend was added without a version suffix branch.

Related errors

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