pypa/pip · error · MetadataInconsistent

Requested {ireq} has inconsistent name: expected {f_val!r},

Error message

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

What it means

MetadataInconsistent raised in _check_metadata_consistency when the project name recorded on the InstallRequirement (from filename, #egg=, or requirement line) does not match the canonical name in the built/fetched distribution metadata. pip refuses to proceed because the resolver picked a candidate for one name but the artifact declares another.

Source

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

    def version(self) -> Version:
        if self._version is None:
            self._version = self.dist.version
        return self._version

    def format_for_error(self) -> str:
        return (
            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:

View on GitHub (pinned to d7d0d0a394)

Solutions

Update the requirement specifier to use the project's actual canonical name as declared in its metadata.
Remove any stale #egg=oldname hint from URL/path requirements.
Rebuild the local sdist/wheel so its filename name matches the metadata project name.
If the index is wrong, report/fix the republished artifact on the private index.

Example fix

# before
pip install "foo @ https://example.com/foo-1.0.tar.gz#egg=foo"
# (metadata actually declares project 'Foo-Bar')

# after
pip install "foo-bar @ https://example.com/foo-1.0.tar.gz"

Defensive patterns

Strategy: validation

Validate before calling

from packaging.utils import canonicalize_name

def check_name_matches_metadata(req_name, dist_metadata_name):
    if canonicalize_name(req_name) != canonicalize_name(dist_metadata_name):
        raise ValueError(
            f"requirement name {req_name!r} != metadata name {dist_metadata_name!r}"
        )
# call before pinning: read METADATA/project_name from the artifact and compare

Try / catch

try:
    pip_install(req)
except InstallationError as e:
    if 'inconsistent name' in str(e):
        # refresh the requirement name from the artifact's actual metadata
        req = derive_name_from_metadata(artifact_url)
        pip_install(req)
    else:
        raise

Prevention

Don't use stale #egg= hints; let pip infer names.
Pin packages by their canonical project name (use `packaging.utils.canonicalize_name`).
Rebuild local artifacts after renaming so filename and metadata agree.

When it happens

Trigger: self._name is set and self._name != dist.canonical_name after _prepare_distribution(). E.g. requirement `foo @ https://example.com/foo-1.0.tar.gz` whose setup.py/pyproject.toml names the project `Foo-Bar`; or a stale #egg=foo hint pointing at a renamed package; or a yanked/republished index file whose filename name differs from its METADATA name.

Common situations: A package was renamed on PyPI but you pinned the old name; a local sdist/wheel whose project_name drifted from its directory name; a mirror or private index serving a file under a mismatched filename; typo in a URL requirement's #egg= fragment.

Related errors

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