{"record":{"id":"430e370bb5ac46dd","repo":"pypa/pip","slug":"error-decoding-path-r-e-r","errorCode":null,"errorMessage":"error decoding {path!r}: {e!r}","messagePattern":"error decoding (.+?): (.+?)","errorType":"exception","errorClass":"UnsupportedWheel","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/utils/wheel.py","lineNumber":87,"sourceCode":"        return source.read(path)\n        # BadZipFile for general corruption, KeyError for missing entry,\n        # and RuntimeError for password-protected files\n    except (BadZipFile, KeyError, RuntimeError) as e:\n        raise UnsupportedWheel(f\"could not read {path!r} file: {e!r}\")\n\n\ndef wheel_metadata(source: ZipFile, dist_info_dir: str) -> Message:\n    \"\"\"Return the WHEEL metadata of an extracted wheel, if possible.\n    Otherwise, raise UnsupportedWheel.\n    \"\"\"\n    path = f\"{dist_info_dir}/WHEEL\"\n    # Zip file path separators must be /\n    wheel_contents = read_wheel_metadata_file(source, path)\n\n    try:\n        wheel_text = wheel_contents.decode()\n    except UnicodeDecodeError as e:\n        raise UnsupportedWheel(f\"error decoding {path!r}: {e!r}\")\n\n    # FeedParser (used by Parser) does not raise any exceptions. The returned\n    # message may have .defects populated, but for backwards-compatibility we\n    # currently ignore them.\n    return Parser().parsestr(wheel_text)\n\n\ndef wheel_version(wheel_data: Message) -> tuple[int, ...]:\n    \"\"\"Given WHEEL metadata, return the parsed Wheel-Version.\n    Otherwise, raise UnsupportedWheel.\n    \"\"\"\n    version_text = wheel_data[\"Wheel-Version\"]\n    if version_text is None:\n        raise UnsupportedWheel(\"WHEEL is missing Wheel-Version\")\n\n    version = version_text.strip()\n\n    try:","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/utils/wheel.py#L69-L105","documentation":"Raised by wheel_metadata() when the WHEEL metadata file content cannot be decoded as text (UnicodeDecodeError). The WHEEL file must be ASCII or UTF-8 text; a decode failure means the file contains invalid byte sequences.","triggerScenarios":"Calling wheel_metadata(source, dist_info_dir) where the WHEEL file bytes raise UnicodeDecodeError on .decode(). Reached during wheel installation via parse_wheel().","commonSituations":"A wheel built by a tool that wrote the WHEEL file in a non-UTF-8 encoding (e.g. Latin-1 with non-ASCII characters). A corrupt WHEEL file containing binary garbage. A wheel assembled by hand with incorrectly encoded metadata.","solutions":["Inspect the WHEEL file encoding: 'unzip -p <file>.whl \"*.dist-info/WHEEL\" | file -'","Rebuild the wheel with a standard build backend (setuptools/hatchling/flit)","If you control the build, ensure the WHEEL file is written as UTF-8 or ASCII","Re-download the wheel from the official index"],"exampleFix":"// before\npip install ./handmade-1.0-py3-none-any.whl  # WHEEL file in Latin-1\n// after\n# rebuild with a standard backend that emits UTF-8 metadata\npython -m build --wheel\npip install dist/handmade-1.0-py3-none-any.whl","handlingStrategy":"validation","validationCode":"import zipfile\n\ndef wheel_metadata_is_decodable(path: str) -> bool:\n    with zipfile.ZipFile(path) as zf:\n        for name in zf.namelist():\n            if name.endswith('.dist-info/WHEEL'):\n                try:\n                    zf.read(name).decode()\n                    return True\n                except UnicodeDecodeError:\n                    return False\n    return False","typeGuard":"def is_decodable_text(data: bytes) -> bool:\n    try:\n        data.decode('utf-8')\n        return True\n    except UnicodeDecodeError:\n        return False","tryCatchPattern":"from pip._internal.exceptions import UnsupportedWheel\n\ntry:\n    wheel_metadata(wheel_zip, dist_info_dir)\nexcept UnsupportedWheel as e:\n    if 'error decoding' in str(e):\n        raise PackagingError(f'WHEEL file has invalid encoding: {e}')\n    raise","preventionTips":["Build wheels with standard backends that write UTF-8 metadata","Never hand-edit WHEEL files in a non-UTF-8 encoding","Verify encoding: 'unzip -p <file>.whl *.dist-info/WHEEL | file -'","Rebuild from source if encoding is wrong"],"tags":["wheel","metadata","encoding","unicode","installation"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}