{"id":"cda59a7c56353c28","repo":"pypa/pip","slug":"error-decoding-metadata-for-self-wheel-name-e","errorCode":null,"errorMessage":"Error decoding metadata for {self._wheel_name}: {e} in {name} file","messagePattern":"Error decoding metadata for (.+?): (.+?) in (.+?) file","errorType":"exception","errorClass":"UnsupportedWheel","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/metadata/pkg_resources.py","lineNumber":68,"sourceCode":"class InMemoryMetadata:\n    \"\"\"IMetadataProvider that reads metadata files from a dictionary.\n\n    This also maps metadata decoding exceptions to our internal exception type.\n    \"\"\"\n\n    def __init__(self, metadata: Mapping[str, bytes], wheel_name: str) -> None:\n        self._metadata = metadata\n        self._wheel_name = wheel_name\n\n    def has_metadata(self, name: str) -> bool:\n        return name in self._metadata\n\n    def get_metadata(self, name: str) -> str:\n        try:\n            return self._metadata[name].decode()\n        except UnicodeDecodeError as e:\n            # Augment the default error with the origin of the file.\n            raise UnsupportedWheel(\n                f\"Error decoding metadata for {self._wheel_name}: {e} in {name} file\"\n            )\n\n    def get_metadata_lines(self, name: str) -> Iterable[str]:\n        return pkg_resources.yield_lines(self.get_metadata(name))\n\n    def metadata_isdir(self, name: str) -> bool:\n        return False\n\n    def metadata_listdir(self, name: str) -> list[str]:\n        return []\n\n    def run_script(self, script_name: str, namespace: str) -> None:\n        pass\n\n\nclass Distribution(BaseDistribution):\n    def __init__(self, dist: pkg_resources.Distribution) -> None:","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/metadata/pkg_resources.py#L50-L86","documentation":"UnsupportedWheel raised by InMemoryMetadata.get_metadata() (pkg_resources backend) when a metadata file's bytes cannot be decoded (UnicodeDecodeError). Mirrors the importlib-backend equivalent: the wheel is a valid zip but a metadata file is not decodable as text.","triggerScenarios":"Reached when get_metadata(name) calls self._metadata[name].decode() and the bytes are not valid UTF-8 (default decode). The wheel name and offending file are included in the message.","commonSituations":"A legacy wheel whose METADATA/entry_points were written in a non-UTF-8 encoding; a corrupt wheel; a wheel produced by an old setuptools on a non-UTF-8 locale.","solutions":["Rebuild the wheel with a current backend that emits UTF-8 metadata.","Re-download the wheel from PyPI (verify hash) to rule out corruption.","Install from sdist (--no-binary) to bypass the wheel.","Report to the maintainer if a published wheel is affected."],"exampleFix":"# before\npip install somepkg-1.0-py2.py3-none-any.whl  # legacy latin-1 METADATA\n\n# after\npip install --no-binary somepkg somepkg\n# or rebuild\npython -m build --wheel","handlingStrategy":"validation","validationCode":"import zipfile\nwith zipfile.ZipFile(wheel_path) as zf:\n    info_dir = next(n.split('/')[0] for n in zf.namelist() if n.endswith('.dist-info/METADATA'))\n    data = zf.read(f'{info_dir}/METADATA')\n    try:\n        data.decode('utf-8')\n    except UnicodeDecodeError:\n        print(f'METADATA in {wheel_path} not UTF-8')","typeGuard":"def wheel_metadata_decodable(path: str) -> bool:\n    import zipfile\n    try:\n        with zipfile.ZipFile(path) as zf:\n            for n in zf.namelist():\n                if n.endswith(('.dist-info/METADATA', '.dist-info/WHEEL')):\n                    zf.read(n).decode('utf-8')\n        return True\n    except (UnicodeDecodeError, zipfile.BadZipFile):\n        return False","tryCatchPattern":"from pip._internal.exceptions import UnsupportedWheel\ntry:\n    dist = Distribution.from_wheel(wheel, name)\nexcept UnsupportedWheel as e:\n    if 'decoding metadata' in str(e):\n        # rebuild/re-download wheel; fall back to sdist\n        ...","preventionTips":["Build wheels with UTF-8 metadata using current backends.","Verify hashes after download to catch corruption.","Use --no-binary to build from sdist for legacy wheels.","Report published wheels with non-UTF-8 metadata."],"tags":["metadata","wheel","encoding","pkg-resources","utf-8"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}