{"id":"35f3f904e36c6165","repo":"pypa/pip","slug":"wheel-has-unexpected-file-name-expected-dist-ver","errorCode":null,"errorMessage":"Wheel has unexpected file name: expected {dist_verstr!r}, got {w.version!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":103,"sourceCode":"    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)\n    if metadata_version >= Version(\"1.2\") and not isinstance(dist.version, Version):\n        raise UnsupportedWheel(\n            f\"Metadata 1.2 mandates PEP 440 version, but {dist_verstr!r} is not\"\n        )\n\n\ndef _build_one(","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/wheel_builder.py#L85-L121","documentation":"Raised by `_verify_one` after building a wheel: the version recorded in the wheel filename (`w.version`) must match the version reported by the wheel's metadata (`dist.version`) after canonicalization. A mismatch indicates the wheel filename version and the `METADATA` Version field disagree — a sign of a broken build, stale egg-info, or a backend that emits inconsistent version strings.","triggerScenarios":"In `_verify_one`, after `dist = get_wheel_distribution(...)`, `canonicalize_version(dist_verstr) != canonicalize_version(w.version)`. Happens when the filename was generated with one version (e.g. from `setup.py sdist` cache) but `METADATA` reports another.","commonSituations":"Stale `*.egg-info` directory left from an older version causing the filename to use the old version while metadata uses the new; dynamic versioning (setuptools_scm) computed differently across build stages; a hand-edited wheel filename; partial build artefacts from a previous release.","solutions":["Clean all build artefacts: `rm -rf build/ dist/ *.egg-info src/*.egg-info` and rebuild.","Ensure version computation is deterministic — for dynamic versioning (setuptools_scm) confirm the same version is resolved at sdist and wheel stages.","Inspect `dist/*.whl`'s `*.dist-info/METADATA` `Version:` line vs. the wheel filename to confirm the discrepancy source.","If you hand-renamed the .whl file, restore the original filename."],"exampleFix":"# before (stale egg-info forces old version into filename)\n$ pip wheel .\n-> InvalidWheelFilename: expected '1.0.0', got '0.9.0'\n\n# after\n$ rm -rf build/ dist/ src/mypkg.egg-info\n$ pip wheel .","handlingStrategy":"validation","validationCode":"from pip._internal.utils.wheel import Wheel\nfrom pip._internal.utils.misc import canonicalize_version\nfrom pip._internal.metadata import get_wheel_distribution\nfrom pip._internal.models.direct_url import FilesystemWheel\nimport os\n\ndef verify_wheel_version(wheel_path: str) -> None:\n    w = Wheel(os.path.basename(wheel_path))\n    dist = get_wheel_distribution(FilesystemWheel(wheel_path), w.name)\n    if canonicalize_version(str(dist.version)) != canonicalize_version(w.version):\n        raise ValueError(f\"Filename version {w.version!r} != metadata {dist.version!r}\")","typeGuard":"null","tryCatchPattern":"from pip._internal.exceptions import InvalidWheelFilename\ntry:\n    _verify_one(req, wheel_path)\nexcept InvalidWheelFilename as e:\n    # version mismatch -> clean stale egg-info and rebuild\n    ...","preventionTips":["Always clean stale `*.egg-info` before building (`rm -rf build/ dist/ *.egg-info`).","Make dynamic version resolution deterministic (e.g. pin setuptools_scm config).","CI: build wheel and verify `*.dist-info/METADATA` Version matches filename before publishing."],"tags":["wheel","packaging","versioning","build"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}