pypa/pip · error · ValueError

Missing 'Version:' header and/or

Error message

Missing 'Version:' header and/or {} file at path: {}

What it means

Raised as ValueError in the Distribution.version property at line 3019-3024 when _get_version() returns None. This means neither the Distribution object was given an explicit version, nor could a 'Version:' header be found in the PKG-INFO metadata file. The error message includes the PKG_INFO path for diagnosis.

Solutions

1. Check the PKG-INFO file at the reported path for a 'Version:' header and add it if missing.
2. Reinstall the package to regenerate complete metadata.
3. If constructing Distribution manually, pass version explicitly to the constructor.
4. Verify the metadata directory (egg-info/dist-info) is not truncated or empty.

Example fix

// before: PKG-INFO missing Version line
// Metadata-Version: 2.1
// Name: mypackage
// (no Version: header)

// after
// Metadata-Version: 2.1
// Name: mypackage
// Version: 1.0.0

def has_version_in_metadata(dist) -> bool:
    try:
        _ = dist.version
        return True
    except ValueError:
        return False

def distribution_has_version(dist) -> bool:
    try:
        v = dist._version
        return True
    except AttributeError:
        try:
            from pkg_resources import _version_from_file
            lines = dist._get_metadata(dist.PKG_INFO)
            return _version_from_file(lines) is not None
        except Exception:
            return False

try:
    version = dist.version
except ValueError:
    version = 'unknown'
    # log: PKG-INFO missing Version header at {path}

When it happens

Trigger: Accessing `dist.version` on a Distribution whose metadata lacks a 'Version:' header. This flows through _get_version() which calls _version_from_file(); if the PKG-INFO file is missing or has no Version line, version resolves to None and the property raises.

Common situations: Corrupt or incomplete .egg-info/dist-info directories missing the Version field; manually constructed Distribution objects without a version; old metadata format (pre-PEP 314) that omits Version; partially installed packages.

Related errors

• Bad metadata in (invalid metadata entry `version`)
• Duplicate entry point
• Entry point %r not found
• Entry points must be listed in groups
• Error decoding metadata for

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/9f3eaa4545709865. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_vendor/pkg_resources/__init__.py:3024

            *************************************************************************
            \n\n!!
            """
            warnings.warn(msg, DeprecationWarning)

            return self._parsed_version

    @property
    def version(self):
        try:
            return self._version
        except AttributeError as e:
            version = self._get_version()
            if version is None:
                path = self._get_metadata_path_for_display(self.PKG_INFO)
                msg = ("Missing 'Version:' header and/or {} file at path: {}").format(
                    self.PKG_INFO, path
                )
                raise ValueError(msg, self) from e

            return version

    @property
    def _dep_map(self):
        """
        A map of extra to its list of (direct) requirements
        for this distribution, including the null extra.
        """
        try:
            return self.__dep_map
        except AttributeError:
            self.__dep_map = self._filter_extras(self._build_dep_map())
        return self.__dep_map

    @staticmethod
    def _filter_extras(dm: dict[str | None, list[Requirement]]):
        """

View on GitHub (pinned to f399c37189)