python-poetry/poetry · error · ValueError

Unknown metadata version: {dist.metadata_version}

Error message

Unknown metadata version: {dist.metadata_version}

What it means

Raised by PackageInfo._from_distribution at src/poetry/inspection/info.py:270-273 when the distribution's metadata_version is missing or its MAJOR component is not among the major versions pkginfo knows about (HEADER_ATTRS keys). pkginfo itself only warns on unknown versions, so Poetry adds a hard fail to avoid silently mis-parsing fields.

Source

Thrown at src/poetry/inspection/info.py:273

    @classmethod
    def _from_distribution(
        cls, dist: pkginfo.BDist | pkginfo.SDist | pkginfo.Wheel
    ) -> PackageInfo:
        """
        Helper method to parse package information from a `pkginfo.Distribution`
        instance.

        :param dist: The distribution instance to parse information from.
        """
        # If the METADATA version is greater than the highest supported version,
        # pkginfo prints a warning and tries to parse the fields from the highest
        # known version. Assuming that METADATA versions adhere to semver,
        # this should be safe for minor updates.
        if not dist.metadata_version or dist.metadata_version.split(".")[0] not in {
            v.split(".")[0] for v in pkginfo.distribution.HEADER_ATTRS
        }:
            raise ValueError(f"Unknown metadata version: {dist.metadata_version}")

        requirements = cls._requirements_from_distribution(dist)

        info = cls(
            name=dist.name,
            version=dist.version,
            summary=dist.summary,
            requires_dist=requirements,
            requires_python=dist.requires_python,
        )

        info._source_type = "file"
        info._source_url = Path(dist.filename).resolve().as_posix()

        return info

    @classmethod
    def _from_sdist_file(cls, path: Path) -> PackageInfo:

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Upgrade poetry (and its bundled pkginfo) to a release that supports the metadata version: `poetry self update` or reinstall in pipx.
2. Rebuild the wheel with a mainstream setuptools version to emit a widely-supported Metadata-Version.
3. Inspect the wheel's METADATA file and down-level the Metadata-Version header if you control the artifact.

Example fix

# inspect before fixing
$ unzip -p dist/pkg-1.0-py3-none-any.whl '*/METADATA' | head -1
Metadata-Version: 2.3

# fix: upgrade poetry so its pkginfo knows 2.3
$ pipx upgrade poetry

import pkginfo

dist = pkginfo.Wheel(str(path))  # or SDist / BDist
known_majors = {v.split('.')[0] for v in pkginfo.distribution.HEADER_ATTRS}
if not dist.metadata_version or dist.metadata_version.split('.')[0] not in known_majors:
    raise ValueError(f'Unsupported Metadata-Version: {dist.metadata_version}; upgrade pkginfo/poetry.')

from poetry.inspection.info import PackageInfo

try:
    info = PackageInfo.from_path(path)
except ValueError as e:
    if 'Unknown metadata version' in str(e):
        raise SystemExit('Upgrade poetry (and bundled pkginfo) to read this wheel.') from e
    raise

When it happens

Trigger: Reading a wheel/sdist whose METADATA uses a newer metadata-spec major version than the installed `pkginfo` library supports, or whose metadata_version is blank. Triggered via PackageInfo.from_path → _from_distribution during inspection/resolution.

Common situations: A wheel built with a bleeding-edge setuptools producing Metadata-Version 2.2/2.3 while the installed pkginfo predates it; a corrupt archive; or an exotic packaging tool emitting an unusual metadata_version.

Related errors

• Unable to retrieve the package version for {name}
• Unable to create package with no name for {root_dir}
• METADATA not found in wheel
• Invalid author string. Must be in the format: John Smith <jo
• Invalid version constraint: {constraint}

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/42162f6081b4182c.json. Report an issue: GitHub.