pypa/pip · error · MetadataInconsistent

Requested {ireq} has inconsistent version: expected {f_val!r

Error message

Requested {ireq} has inconsistent version: expected {f_val!r}, but metadata has {m_val!r}

What it means

MetadataInconsistent raised when the version inferred for the InstallRequirement (from filename, specifier, or metadata sidecar) disagrees with the version in the finally-prepared distribution metadata. This protects the resolver from installing a candidate whose graph was computed against a different version than what actually ships.

Source

Thrown at src/pip/_internal/resolution/resolvelib/candidates.py:229

            f"{self.name} {self.version} "
            f"(from {'editable ' if self.is_editable else ''}"
            f"{self._link.file_path if self._link.is_file else self._link})"
        )

    def _prepare_distribution(self) -> BaseDistribution:
        raise NotImplementedError("Override in subclass")

    def _check_metadata_consistency(self, dist: BaseDistribution) -> None:
        """Check for consistency of project name and version of dist."""
        if self._name is not None and self._name != dist.canonical_name:
            raise MetadataInconsistent(
                self._ireq,
                "name",
                self._name,
                dist.canonical_name,
            )
        if self._version is not None and self._version != dist.version:
            raise MetadataInconsistent(
                self._ireq,
                "version",
                str(self._version),
                str(dist.version),
            )
        # check dependencies are valid
        # TODO performance: this means we iterate the dependencies at least twice,
        # we may want to cache parsed Requires-Dist
        try:
            list(dist.iter_dependencies(list(dist.iter_provided_extras())))
        except InvalidRequirement as e:
            raise MetadataInvalid(self._ireq, str(e))

    def _prepare(self) -> BaseDistribution:
        try:
            dist = self._prepare_distribution()
        except HashError as e:
            # Provide HashError the underlying ireq that caused it. This

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Reinstall from the canonical index/PyPI where filename and metadata agree.
2. Rebuild the local artifact so its version (filename + metadata) is consistent.
3. If using a private index, fix or purge the mismatched file and its .metadata sidecar.
4. Pin the version explicitly with == to the value the metadata actually declares.

Example fix

# before - filename says 1.0, metadata says 1.0.1
pip install ./mypkg-1.0.tar.gz

# after - rebuild with consistent version, then install
# (in mypkg/) bump version to 1.0.1, python -m build
pip install ./mypkg-1.0.1.tar.gz

from packaging.version import Version

def check_version_matches(filename_version, metadata_version):
    if Version(filename_version) != Version(metadata_version):
        raise ValueError(f"filename version {filename_version} != metadata {metadata_version}")
# verify before publishing or pinning a local artifact

try:
    pip_install(req)
except InstallationError as e:
    if 'inconsistent version' in str(e):
        actual = parse_version_from_error(e)
        pip_install(f"{name}=={actual}")
    else:
        raise

When it happens

Trigger: self._version is not None and self._version != dist.version after _prepare_distribution(). Happens with URL/path installs whose filename implies 1.0 but whose metadata says 1.0.1; with PEP 658 .metadata sidecars that disagree with the wheel's embedded METADATA (see also SidecarMetadataInconsistent); or with republished/misnamed files on an index.

Common situations: A wheel was re-uploaded under an old filename after a version bump; a private index serves mismatched .metadata sidecars; a local sdist whose VERSION/__version__ differs from the filename; partial/failed re-publish to a mirror.

Related errors

• Requested {ireq} has inconsistent name: expected {f_val!r},
• Requested {ireq} has invalid metadata: {error}
• Invalid Metadata-Version: {metadata_version_value}
• Metadata 1.2 mandates PEP 440 version, but {dist_verstr!r} i
• Requested {ireq} has invalid metadata: Requires-Dist in {sou

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/aaddb2fface5d624.json. Report an issue: GitHub.