What causes "Invalid wheel filename format: {wheel_name}" in vllm-project/vllm?

List the install directory and find the file whose name has fewer than 5 dash-separated parts (excluding .whl)

vllm-project/vllm · error · ValueError

Invalid wheel filename format: {wheel_name}

Error message

Invalid wheel filename format: {wheel_name}

What it means

get_wheel_version() in tools/vllm-rocm/pin_rocm_dependencies.py parses PEP 427 wheel filenames: {distribution}-{version}(-{build tag})?-{python}-{abi}-{platform}.whl, i.e. at least 5 dash-separated parts after stripping '.whl'. Fewer than 5 parts means the name is not a valid wheel filename (or not a wheel at all), so version extraction at parts[1] would be meaningless and it raises ValueError.

Source

Thrown at tools/vllm-rocm/pin_rocm_dependencies.py:33

from pathlib import Path

import regex as re


def extract_version_from_wheel(wheel_name: str) -> str:
    """
    Extract version from wheel filename.

    Example:
        torch-2.9.0a0+git1c57644-cp312-cp312-linux_x86_64.whl -> 2.9.0a0+git1c57644
        triton-3.4.0-cp312-cp312-linux_x86_64.whl -> 3.4.0
    """
    # Wheel format:
    #    {distribution}-{version}(-{build tag})?-{python}-{abi}-{platform}.whl
    parts = wheel_name.replace(".whl", "").split("-")

    if len(parts) < 5:
        raise ValueError(f"Invalid wheel filename format: {wheel_name}")

    # Version is the second part
    version = parts[1]
    return version


def get_custom_wheel_versions(install_dir: str) -> dict[str, str]:
    """
    Read /install directory and extract versions of custom wheels.

    Returns:
        Dict mapping package names to exact versions
    """
    install_path = Path(install_dir)
    if not install_path.exists():
        print(f"ERROR: Install directory not found: {install_dir}", file=sys.stderr)
        sys.exit(1)

View on GitHub (pinned to c794754062)

Solutions

List the install directory and find the file whose name has fewer than 5 dash-separated parts (excluding .whl)
Restore the canonical wheel filename with full tags, e.g. triton-3.4.0-cp312-cp312-linux_x86_64.whl — re-download or re-copy it without renaming
Remove non-wheel or placeholder files ending in .whl from the directory
If you control artifact naming in CI, stop truncating wheel filenames when publishing/copying

Example fix

# before (renamed wheel, only 2 parts)
/install/torch-rocm-2.9.0.whl
# after (full PEP 427 name)
/install/torch-2.9.0a0+git1c57644-cp312-cp312-linux_x86_64.whl

Defensive patterns

Strategy: validation

Validate before calling

import re
WHEEL_RE = re.compile(r"^[^-]+-[^-]+(-[^-]+)?-[^-]+-[^-]+-[^-]+\.whl$")
for name in os.listdir(install_dir):
    if name.endswith(".whl") and not WHEEL_RE.match(name):
        raise SystemExit(f"malformed wheel filename: {name}")

Type guard

def is_valid_wheel_name(name: str) -> bool:
    return name.endswith(".whl") and len(name[:-4].split("-")) >= 5

Try / catch

try:
    version = get_custom_wheel_versions(install_dir)
except ValueError as e:
    print(f"skipping malformed wheel: {e}")
    return {}

Prevention

Never rename wheel artifacts — tags are load-bearing for version parsing and pip
Validate artifact filenames in the CI step that publishes/copies wheels
Keep sdists (.tar.gz) out of directories the pinner scans for wheels

When it happens

Trigger: The /install directory scanned for custom ROCm wheels contains a malformed filename — e.g. 'torch.whl' (distribution only), 'torch-2.9.0.whl' (no tag parts), a renamed wheel like 'torch-custom.whl', or a non-wheel file that happens to end in .whl. Also triggered if '.whl' was double-stripped or the name uses underscores where dashes are required.

Common situations: Manually renaming downloaded wheels for caching (losing tag segments); a build script copying artifacts with truncated names; pointing the install dir at a folder with placeholder/symlink files; sdists (.tar.gz) renamed to .whl.

Related errors

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