pypa/pip · error · InvalidWheelFilename

Wheel has unexpected file name: expected {canonical_name!r},

Error message

Wheel has unexpected file name: expected {canonical_name!r}, got {w.name!r}

What it means

Raised by `pip._internal.wheel_builder._verify_one` while validating a built wheel. After building, pip parses the wheel filename with `Wheel(...)` and checks that the name embedded in the filename matches the canonicalized requirement name (`canonicalize_name(req.name)`). A mismatch means the wheel filename does not correspond to the package being built — typically a packaging misconfiguration in the project (wrong `name` in setup.py/setup.cfg/pyproject).

Source

Thrown at src/pip/_internal/wheel_builder.py:96

    wheel_cache: WheelCache,
) -> str:
    """Return the persistent or temporary cache directory where the built
    wheel need to be stored.
    """
    cache_available = bool(wheel_cache.cache_dir)
    assert req.link
    if cache_available and _should_cache(req):
        cache_dir = wheel_cache.get_path_for_link(req.link)
    else:
        cache_dir = wheel_cache.get_ephem_path_for_link(req.link)
    return cache_dir


def _verify_one(req: InstallRequirement, wheel_path: str) -> None:
    canonical_name = canonicalize_name(req.name or "")
    w = Wheel(os.path.basename(wheel_path))
    if w.name != canonical_name:
        raise InvalidWheelFilename(
            f"Wheel has unexpected file name: expected {canonical_name!r}, "
            f"got {w.name!r}",
        )
    dist = get_wheel_distribution(FilesystemWheel(wheel_path), canonical_name)
    dist_verstr = str(dist.version)
    if canonicalize_version(dist_verstr) != canonicalize_version(w.version):
        raise InvalidWheelFilename(
            f"Wheel has unexpected file name: expected {dist_verstr!r}, "
            f"got {w.version!r}",
        )
    metadata_version_value = dist.metadata_version
    if metadata_version_value is None:
        raise UnsupportedWheel("Missing Metadata-Version")
    try:
        metadata_version = Version(metadata_version_value)
    except InvalidVersion:
        msg = f"Invalid Metadata-Version: {metadata_version_value}"
        raise UnsupportedWheel(msg)

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Check the `name` field in your `pyproject.toml`/`setup.py`/`setup.cfg` matches the requirement you passed to pip.
2. Rebuild cleanly (`rm -rf build/ *.egg-info`) to discard stale metadata from a previous name.
3. If the package was intentionally renamed, update all requirement references to the new name.
4. Verify the wheel filename with `unzip -l dist/*.whl` and inspect `*.dist-info/METADATA` for the real name.

Example fix

# before
# pyproject.toml
[project]
name = "OldName"
# but built via: pip wheel .  (requirement name "NewName")

# after
[project]
name = "NewName"
# then rebuild: rm -rf build/ src/*.egg-info dist/ && pip wheel .

from pip._internal.utils.misc import canonicalize_name
from pip._internal.utils.wheel import Wheel
import os

def verify_wheel_name(req_name: str, wheel_path: str) -> None:
    canonical = canonicalize_name(req_name)
    w = Wheel(os.path.basename(wheel_path))
    if w.name != canonical:
        raise ValueError(f"Wheel name {w.name!r} != requirement {canonical!r}")

null

from pip._internal.exceptions import InvalidWheelFilename
try:
    _verify_one(req, wheel_path)
except InvalidWheelFilename as e:
    # name mismatch -> fix [project].name / clean egg-info
    ...

When it happens

Trigger: `_verify_one(req, wheel_path)` builds the wheel for `req`, instantiates `Wheel(os.path.basename(wheel_path))`, and finds `w.name != canonical_name`. Triggered on any `pip wheel`/`pip install` of a project whose built wheel filename's project name does not canonicalize to the requirement's name.

Common situations: A project whose `[project] name` in pyproject.toml differs from the requirement used to build it; a renamed package where the requirement string was not updated; sdist-to-wheel builds where the build backend produces a different distribution name; case/normalization surprises (e.g. underscores vs dashes handled, but genuine renames are not).

Related errors

• Wheel has unexpected file name: expected {dist_verstr!r}, go
• Missing Metadata-Version
• Invalid Metadata-Version: {metadata_version_value}
• Metadata 1.2 mandates PEP 440 version, but {dist_verstr!r} i
• Invalid project name: {filename!r}

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/ecdb1390f48cc51f.json. Report an issue: GitHub.