{"record":{"id":"0eac9f25c945dbe1","repo":"pypa/pip","slug":"error-decoding-metadata-for-wheel-e-in-filen","errorCode":null,"errorMessage":"Error decoding metadata for {wheel}: {e} in {filename} file","messagePattern":"Error decoding metadata for (.+?): (.+?) in (.+?) file","errorType":"exception","errorClass":"UnsupportedWheel","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/metadata/importlib/_dists.py","lineNumber":93,"sourceCode":"        return cls(files, info_location)\n\n    def iterdir(self, path: InfoPath) -> Iterator[pathlib.PurePosixPath]:\n        # Only allow iterating through the metadata directory.\n        if pathlib.PurePosixPath(str(path)) in self._files:\n            return iter(self._files)\n        raise FileNotFoundError(path)\n\n    def read_text(self, filename: str) -> str | None:\n        try:\n            data = self._files[pathlib.PurePosixPath(filename)]\n        except KeyError:\n            return None\n        try:\n            text = data.decode(\"utf-8\")\n        except UnicodeDecodeError as e:\n            wheel = self.info_location.parent\n            error = f\"Error decoding metadata for {wheel}: {e} in {filename} file\"\n            raise UnsupportedWheel(error)\n        return text\n\n    def locate_file(self, path: str | PathLike[str]) -> pathlib.Path:\n        # This method doesn't make sense for our in-memory wheel, but the API\n        # requires us to define it.\n        raise NotImplementedError\n\n\nclass Distribution(BaseDistribution):\n    def __init__(\n        self,\n        dist: importlib.metadata.Distribution,\n        info_location: BasePath | None,\n        installed_location: BasePath | None,\n    ) -> None:\n        self._dist = dist\n        self._info_location = info_location\n        self._installed_location = installed_location","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/metadata/importlib/_dists.py#L75-L111","documentation":"Raised as UnsupportedWheel from WheelDistribution.read_text in _dists.py:88-93. When reading a metadata file out of an in-memory wheel, if the bytes fail to decode as UTF-8 (UnicodeDecodeError), pip wraps it with the wheel location and offending filename because non-UTF-8 metadata is not spec-compliant and cannot be parsed.","triggerScenarios":"Distribution.from_wheel -> WheelDistribution.from_zipfile reads a file (e.g. METADATA/RECORD) from the wheel zip; the bytes raise UnicodeDecodeError on .decode('utf-8'); UnsupportedWheel is raised.","commonSituations":"A wheel whose METADATA was authored in a legacy/non-UTF-8 encoding (Latin-1, cp1252); a corrupted or truncated wheel where decode fails; a wheel produced by a broken build tool that wrote binary into a text metadata field.","solutions":["Obtain a replacement wheel from a different source/version that has UTF-8 metadata.","Rebuild the wheel with a compliant build backend (setuptools/poetry/hatch) that writes UTF-8 METADATA.","If you control the package, ensure all metadata files are UTF-8 encoded."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before reading wheel metadata, verify it decodes as UTF-8:\nwith wheel.as_zipfile() as zf:\n    for p in zf.namelist():\n        if p.endswith(('.dist-info/METADATA',)):\n            zf.read(p).decode('utf-8')  # raises early if not UTF-8","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import UnsupportedWheel\ntry:\n    dist = Distribution.from_wheel(wheel, name)\nexcept UnsupportedWheel as e:\n    if 'Error decoding metadata' in str(e):\n        # fetch an alternative wheel or rebuild\n        ...","preventionTips":["Ensure all wheel metadata files are UTF-8 encoded.","Validate wheels with auditwheel/twine check before publishing.","Avoid hand-editing METADATA in non-UTF-8 editors."],"tags":["metadata","wheel","encoding","importlib"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}