vllm-project/vllm · error · RuntimeError

Cannot find CMake executable

Error message

Cannot find CMake executable

What it means

Raised by setup.py's custom build_ext (line 333) when `subprocess.check_output(["cmake", "--version"])` fails with OSError — i.e. no `cmake` executable is resolvable on PATH. Building vLLM from source (C/C++/CUDA extensions) requires CMake at build time; the check fails fast before any compilation starts.

Source

Thrown at setup.py:333

            cmake_args += [f"-DCMAKE_CUDA_COMPILER={CUDA_HOME}/bin/nvcc"]
        elif _is_hip() and ROCM_HOME is not None:
            cmake_args += [f"-DROCM_PATH={ROCM_HOME}"]

        other_cmake_args = os.environ.get("CMAKE_ARGS")
        if other_cmake_args:
            cmake_args += other_cmake_args.split()

        subprocess.check_call(
            ["cmake", ext.cmake_lists_dir, *build_tool, *cmake_args],
            cwd=self.build_temp,
        )

    def build_extensions(self) -> None:
        # Ensure that CMake is present and working
        try:
            subprocess.check_output(["cmake", "--version"])
        except OSError as e:
            raise RuntimeError("Cannot find CMake executable") from e

        # Create build directory if it does not exist.
        if not os.path.exists(self.build_temp):
            os.makedirs(self.build_temp)

        targets = []

        def target_name(s: str) -> str:
            return s.removeprefix("vllm.").removeprefix("vllm_flash_attn.")

        # Build all the extensions
        for ext in self.extensions:
            self.configure(ext)
            targets.append(target_name(ext.name))

        num_jobs, _ = self.compute_num_jobs()

        build_args = [

View on GitHub (pinned to c794754062)

Solutions

1. Install CMake >= 3.26: `pip install cmake` (fastest, puts it next to the build python) or use apt/brew
2. Verify `cmake --version` works in the same environment that runs the build
3. Alternatively avoid the local build: use a precompiled wheel (e.g. VLLM_USE_PRECOMPILED=1 or the precompiled-wheel flow)

Example fix

# before
$ pip install -e .
RuntimeError: Cannot find CMake executable

# after
$ pip install cmake
$ cmake --version   # sanity check
$ pip install -e .

import shutil, subprocess
assert shutil.which("cmake") is not None, "cmake not on PATH; run: pip install cmake"
subprocess.check_output(["cmake", "--version"])  # also catches a broken binary

try:
    subprocess.check_output(["cmake", "--version"])
except OSError:
    raise RuntimeError("Cannot find CMake executable — install with `pip install cmake`") from None

When it happens

Trigger: Running `pip install -e .` or `python setup.py build_ext` without cmake installed, with cmake installed but not on PATH, or with a broken cmake binary (wrong architecture, missing shared libs).

Common situations: Fresh containers/CI images without build tooling; macOS/Windows where cmake is installed via an app not symlinked into PATH; nix/conda environments where the build subprocess does not inherit the shell's PATH.

Related errors

• No compatible wheel found for {arch} at {simple_url}
• Wheel metadata missing path: {wheel}
• HTTP request failed: {0}
• JSON error: {0}
• Tokenizer error: {0}

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