[Build] Find compatible published wheels for precompiled installs (#58871)

Signed-off-by: greg pereira <grpereir@redhat.com>
Signed-off-by: mgoin <mgoin64@gmail.com>
Co-authored-by: mgoin <mgoin64@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Greg Pereira
2026-10-09 08:05:54 -07:00
committed by GitHub
co-authored by mgoin Claude Opus 5.5
parent 970dc63478
commit 90ba2f34b5
4 changed files with 306 additions and 18 deletions
@@ -117,18 +117,21 @@ If you need to recompile the `vllm-rs` Rust frontend binary, you can rebuild and
This will install the required Rust toolchain if needed, build the binary, and place it in `vllm/vllm-rs`.
In case you see an error about wheel not found when running the above command, it might be because the commit you based on in the `main` branch was just merged and its precompiled wheel is not available yet. You can wait around an hour and retry, or set `VLLM_PRECOMPILED_WHEEL_COMMIT=nightly` to automatically select the most recent already-built commit on `main`.
Wheels are published an hour or two after a commit lands on `main`. If the wheel for
your merge-base with upstream `main` is not available yet, the installer uses the
nearest older commit that has one, searching up to 20 commits back. It stops with an
error if compiled sources or build configuration (`csrc/`, `cmake/`, `CMakeLists.txt`,
`pyproject.toml`, `vllm/_custom_ops.py`) changed between that commit and your
merge-base, and warns if `rust/` or `setup.py` did. This is a source-level check, not
a guarantee of binary compatibility.
```bash
export VLLM_PRECOMPILED_WHEEL_COMMIT=nightly
export VLLM_USE_PRECOMPILED=1
uv pip install --editable .
```
Setting `VLLM_PRECOMPILED_WHEEL_LOCATION` or a full SHA in
`VLLM_PRECOMPILED_WHEEL_COMMIT` skips this search and check.
There are more environment variables to control the behavior of Python-only build:
- `VLLM_PRECOMPILED_WHEEL_LOCATION`: specify the exact wheel URL or local file path of a pre-compiled wheel to use. All other logic to find the wheel will be skipped.
- `VLLM_PRECOMPILED_WHEEL_COMMIT`: override the commit hash to download the pre-compiled wheel. It can be `nightly` to use the last **already built** commit on the main branch.
- `VLLM_PRECOMPILED_WHEEL_COMMIT`: override the commit to download the pre-compiled wheel from. Must be a full 40-character SHA.
- `VLLM_PRECOMPILED_WHEEL_VARIANT`: specify the variant subdirectory to use on the nightly index, e.g., `cu129`, `cu130`, `cpu`. If not specified, the variant is auto-detected based on your system's CUDA version (from PyTorch or nvidia-smi). You can also set `VLLM_MAIN_CUDA_VERSION` to override auto-detection.
You can find more information about vLLM's wheels in [Install the latest code](#install-the-latest-code).