{"id":"ecdb1390f48cc51f","repo":"pypa/pip","slug":"wheel-has-unexpected-file-name-expected-canonica","errorCode":null,"errorMessage":"Wheel has unexpected file name: expected {canonical_name!r}, got {w.name!r}","messagePattern":"Wheel has unexpected file name: expected (.+?), got (.+?)","errorType":"validation","errorClass":"InvalidWheelFilename","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/wheel_builder.py","lineNumber":96,"sourceCode":"    wheel_cache: WheelCache,\n) -> str:\n    \"\"\"Return the persistent or temporary cache directory where the built\n    wheel need to be stored.\n    \"\"\"\n    cache_available = bool(wheel_cache.cache_dir)\n    assert req.link\n    if cache_available and _should_cache(req):\n        cache_dir = wheel_cache.get_path_for_link(req.link)\n    else:\n        cache_dir = wheel_cache.get_ephem_path_for_link(req.link)\n    return cache_dir\n\n\ndef _verify_one(req: InstallRequirement, wheel_path: str) -> None:\n    canonical_name = canonicalize_name(req.name or \"\")\n    w = Wheel(os.path.basename(wheel_path))\n    if w.name != canonical_name:\n        raise InvalidWheelFilename(\n            f\"Wheel has unexpected file name: expected {canonical_name!r}, \"\n            f\"got {w.name!r}\",\n        )\n    dist = get_wheel_distribution(FilesystemWheel(wheel_path), canonical_name)\n    dist_verstr = str(dist.version)\n    if canonicalize_version(dist_verstr) != canonicalize_version(w.version):\n        raise InvalidWheelFilename(\n            f\"Wheel has unexpected file name: expected {dist_verstr!r}, \"\n            f\"got {w.version!r}\",\n        )\n    metadata_version_value = dist.metadata_version\n    if metadata_version_value is None:\n        raise UnsupportedWheel(\"Missing Metadata-Version\")\n    try:\n        metadata_version = Version(metadata_version_value)\n    except InvalidVersion:\n        msg = f\"Invalid Metadata-Version: {metadata_version_value}\"\n        raise UnsupportedWheel(msg)","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/wheel_builder.py#L78-L114","documentation":"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).","triggerScenarios":"`_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.","commonSituations":"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).","solutions":["Check the `name` field in your `pyproject.toml`/`setup.py`/`setup.cfg` matches the requirement you passed to pip.","Rebuild cleanly (`rm -rf build/ *.egg-info`) to discard stale metadata from a previous name.","If the package was intentionally renamed, update all requirement references to the new name.","Verify the wheel filename with `unzip -l dist/*.whl` and inspect `*.dist-info/METADATA` for the real name."],"exampleFix":"# before\n# pyproject.toml\n[project]\nname = \"OldName\"\n# but built via: pip wheel .  (requirement name \"NewName\")\n\n# after\n[project]\nname = \"NewName\"\n# then rebuild: rm -rf build/ src/*.egg-info dist/ && pip wheel .","handlingStrategy":"validation","validationCode":"from pip._internal.utils.misc import canonicalize_name\nfrom pip._internal.utils.wheel import Wheel\nimport os\n\ndef verify_wheel_name(req_name: str, wheel_path: str) -> None:\n    canonical = canonicalize_name(req_name)\n    w = Wheel(os.path.basename(wheel_path))\n    if w.name != canonical:\n        raise ValueError(f\"Wheel name {w.name!r} != requirement {canonical!r}\")","typeGuard":"null","tryCatchPattern":"from pip._internal.exceptions import InvalidWheelFilename\ntry:\n    _verify_one(req, wheel_path)\nexcept InvalidWheelFilename as e:\n    # name mismatch -> fix [project].name / clean egg-info\n    ...","preventionTips":["Keep `[project].name` and requirement references in sync on rename.","Clean `build/`, `dist/`, and `*.egg-info` before building.","Run `python -m build --wheel` locally to catch filename mismatches early."],"tags":["wheel","packaging","build","metadata"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}