[Build] Find compatible published wheels for precompiled installs by Gregory-Pereira · Pull Request #58871 · vllm-project/vllm · GitHub
Skip to content

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

Merged
vllm-bot merged 6 commits into
vllm-project:mainfrom
Gregory-Pereira:precompiled-install-filter-on-wheel-availability
Oct 9, 2026
Merged

[Build] Find compatible published wheels for precompiled installs#58871
vllm-bot merged 6 commits into
vllm-project:mainfrom
Gregory-Pereira:precompiled-install-filter-on-wheel-availability

Conversation

@Gregory-Pereira

@Gregory-Pereira Gregory-Pereira commented Sep 27, 2026 •
edited by mgoin
Loading

Copy link
Copy Markdown
Contributor

Purpose

Addresses the gap where recent commits on vLLM main don't exist in the wheels index in the 1-2 hours it takes to populate them. When VLLM_USE_PRECOMPILED is enabled and the VLLM_PRECOMPILED_WHEEL_LOCATION is not a path, this logic will walk backwards through 20 commits in git history to find a commit base that does exist on the vLLM wheels index. It will then attempt to identify if compilation affected source source (csrc/, cmake/, CMakeLists.txt, setup.py, pyproject.toml, vllm/_custom_ops.py, and rust/) has diverged since the that selected precompiled commit. If changes do exist an editable install may or may not cause a failure. For example metadata changes to pyproject.toml wont do anything, or comments in csrc, but it could just as easily cause install failure or succeed at buildings but fail at runtime. To combat this it will warn the use of said precompiled wheel

Test Plan

  • Run .venv/bin/python -u tests/standalone_tests/test_precompiled_wheel.py -v: all 8 tests pass. Covers automatic selection, explicit local/remote wheel overrides (including relative paths), Rust-only bypass, publication lag, compiled-source rejection, architecture matching, missing wheels, and network/server errors.
  • Run git_history_smoke.py using the repository virtual environment: all 5 scenarios pass against temporary real Git repositories. Wheel metadata is mocked. Confirms Python-only feature changes can reuse an older published wheel and rejects committed feature native changes, native changes between the wheel and merge-base, and staged/unstaged native edits. The success scenario uses detached HEAD.
  • Run repository pre-commit hooks on all four changed files: all applicable checks pass.
  • Run the full VLLM_USE_PRECOMPILED=1 uv pip install -e . flow against the live wheel index on Linux. Not run locally: development host is macOS ARM64.

Test Result

All local tests passed:

METADATA FIXTURE: 00f6b72c16ef5bb64f9d5fae5ad05e0bdd56cf96 cu130
METADATA FIXTURE: 121b4fc62b92ca3e813607d583b04fabc97a86d3 cu130
Using compatible precompiled wheel commit 121b4fc62b92ca3e813607d583b04fabc97a86d3
PASS: detached feature HEAD with Python-only changes reuses older published wheel
METADATA FIXTURE: 00f6b72c16ef5bb64f9d5fae5ad05e0bdd56cf96 cu130
METADATA FIXTURE: 121b4fc62b92ca3e813607d583b04fabc97a86d3 cu130
EXPECTED REJECTION:
Cannot verify compatibility of precompiled wheel 121b4fc62b92ca3e813607d583b04fabc97a86d3: compiled sources or build files differ from this checkout. Changed files:
csrc/kernel.cpp
Build vLLM from source (unset VLLM_USE_PRECOMPILED), or rebase onto a commit with a compatible published wheel.
PASS: committed feature native change rejects older wheel
METADATA FIXTURE: ef9a26d3175836386fb4d8246973742c7f37a867 cu130
METADATA FIXTURE: 00f6b72c16ef5bb64f9d5fae5ad05e0bdd56cf96 cu130
METADATA FIXTURE: 121b4fc62b92ca3e813607d583b04fabc97a86d3 cu130
EXPECTED REJECTION:
Cannot verify compatibility of precompiled wheel 121b4fc62b92ca3e813607d583b04fabc97a86d3: compiled sources or build files differ from this checkout. Changed files:
csrc/kernel.cpp
Build vLLM from source (unset VLLM_USE_PRECOMPILED), or rebase onto a commit with a compatible published wheel.
PASS: native changes between wheel commit and merge-base are rejected
METADATA FIXTURE: 00f6b72c16ef5bb64f9d5fae5ad05e0bdd56cf96 cu130
METADATA FIXTURE: 121b4fc62b92ca3e813607d583b04fabc97a86d3 cu130
PASS: unstaged native change rejected
METADATA FIXTURE: 00f6b72c16ef5bb64f9d5fae5ad05e0bdd56cf96 cu130
METADATA FIXTURE: 121b4fc62b92ca3e813607d583b04fabc97a86d3 cu130
PASS: staged native change rejected
RESULT: all 5 real-Git scenarios passed. Metadata was mocked; no wheel installation performed.

---
test_automatic_install_uses_compatible_wheel (__main__.TestCompatibleWheel.test_automatic_install_uses_compatible_wheel) ... VLLM_PRECOMPILED_WHEEL_COMMIT not valid: , trying to fetch base commit in main branch
ok
test_compiled_changes_from_wheel_to_checkout_are_rejected (__main__.TestCompatibleWheel.test_compiled_changes_from_wheel_to_checkout_are_rejected) ... ok
test_exhausted_history_reports_no_published_wheel (__main__.TestCompatibleWheel.test_exhausted_history_reports_no_published_wheel) ... ok
test_explicit_wheel_location_bypasses_selection (__main__.TestCompatibleWheel.test_explicit_wheel_location_bypasses_selection) ... Using user-specified precompiled wheel location: /tmp/local.whl
Using user-specified precompiled wheel location: ./wheels/local.whl
Using user-specified precompiled wheel location: ../local.whl
Using user-specified precompiled wheel location: https://example.com/custom.whl
Using user-specified precompiled wheel location: https://wheels.vllm.ai/custom.whl
ok
test_network_and_server_errors_do_not_trigger_walkback (__main__.TestCompatibleWheel.test_network_and_server_errors_do_not_trigger_walkback) ... ok
test_publication_lag_uses_nearest_available_ancestor (__main__.TestCompatibleWheel.test_publication_lag_uses_nearest_available_ancestor) ... Using compatible precompiled wheel commit older
ok
test_rust_only_install_bypasses_compiled_source_check (__main__.TestCompatibleWheel.test_rust_only_install_bypasses_compiled_source_check) ... VLLM_PRECOMPILED_WHEEL_COMMIT not valid: , trying to fetch base commit in main branch
Using precompiled wheel commit base with variant cu130
Found precompiled wheel metadata: {'package_name': 'vllm', 'platform_tag': 'manylinux_x86_64', 'path': 'wheel.whl', 'filename': 'wheel.whl'}
Using precompiled wheel URL: https://wheels.test/wheel.whl
ok
test_wrong_architecture_is_skipped (__main__.TestCompatibleWheel.test_wrong_architecture_is_skipped) ... Using compatible precompiled wheel commit older
ok

----------------------------------------------------------------------
Ran 8 tests in 0.005s

OK

cc @robertgshaw2-redhat - we discussed this yesterday. Other relevant stakeholders include @wseaton @tlrmchlsmth

@Gregory-Pereira
[Build] Find compatible published wheels for precompiled installs
1563f80 
Signed-off-by: greg pereira <grpereir@redhat.com>
@mergify

mergify Bot commented Sep 27, 2026

Copy link
Copy Markdown
Contributor

@mergify mergify Bot added documentation Improvements or additions to documentation ci/build nvidia labels Sep 27, 2026
@Gregory-Pereira
Gregory-Pereira marked this pull request as ready for review September 27, 2026 16:05
claude[bot]
claude Bot reviewed Sep 27, 2026
View reviewed changes

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

@Gregory-Pereira

Gregory-Pereira commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

cc @mgoin if you have time sir

mgoin and others added 2 commits October 8, 2026 19:42
@mgoin @claude
Scope precompiled wheel walk-back to the publication lag
a818fc1 
Compare the nearest published wheel against the merge-base instead of
the working tree, so a branch's own edits to setup.py, pyproject.toml or
csrc no longer block a precompiled install that works today.

- Search 20 commits back instead of 50 and report the distance.
- Only fail on csrc, cmake, CMakeLists.txt, pyproject.toml and
  vllm/_custom_ops.py; warn for rust and setup.py.
- Keep the nightly fallback when the merge-base cannot be determined.
- Return the commit and reuse the existing download path.
- Test the search against a temporary Git repo.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: mgoin <mgoin64@gmail.com>
@mgoin
Merge branch 'main' into precompiled-install-filter-on-wheel-availabi…
45dc859 
…lity
@mgoin

mgoin commented Oct 8, 2026

Copy link
Copy Markdown
Member

/ci run

@mgoin mgoin added the ready ONLY add when PR is ready to merge/full CI is needed label Oct 8, 2026
@mgoin
mgoin enabled auto-merge (squash) October 8, 2026 19:49
@github-project-automation github-project-automation Bot moved this to Ready in NVIDIA Oct 8, 2026
@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown

✅ Triggered Buildkite CI #93700 for commit 45dc859d98f6.

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown

@vllm-bot
vllm-bot merged commit 90ba2f3 into vllm-project:main Oct 9, 2026
460 of 463 checks passed
@github-project-automation github-project-automation Bot moved this from Ready to Done in NVIDIA Oct 9, 2026
@fangchenli fangchenli mentioned this pull request Oct 14, 2026
Open
6 tasks done
michael-gpu pushed a commit to practical-inference/vllm-ampere-extended that referenced this pull request Oct 20, 2026
@Gregory-Pereira @mgoin @claude
[Build] Find compatible published wheels for precompiled installs (vl…
74dbc8c 
…lm-project#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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@claude claude[bot] claude[bot] left review comments
@mgoin mgoin mgoin approved these changes
@khluu khluu Awaiting requested review from khluu khluu is a code owner
@Harry-Chen Harry-Chen Awaiting requested review from Harry-Chen Harry-Chen is a code owner

Assignees

No one assigned

Labels

ci/build documentation Improvements or additions to documentation nvidia ready ONLY add when PR is ready to merge/full CI is needed

Projects

NVIDIA
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@Gregory-Pereira @mgoin @vllm-bot