pypa/pip · error · MetadataInvalid

Requested {ireq} has invalid metadata: {error}

Error message

Requested {ireq} has invalid metadata: {error}

What it means

MetadataInvalid raised when iterating the prepared distribution's dependencies raises InvalidRequirement — i.e. the artifact's METADATA contains a Requires-Dist (or similar) field that is not a valid PEP 508 requirement string. pip cannot build a dependency graph from malformed metadata, so it aborts the candidate.

Source

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

                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
            # provides context for the resulting error message to show the
            # offending line to the user.
            e.req = self._ireq
            raise
        except InstallationSubprocessError as exc:
            if isinstance(self._ireq.comes_from, InstallRequirement):
                request_chain = self._ireq.comes_from.from_path()
            else:
                request_chain = self._ireq.comes_from

            if request_chain is None:
                request_chain = "directly requested"

View on GitHub (pinned to d7d0d0a394)

Solutions

  1. Upgrade the offending package to a release with corrected metadata, if available.
  2. If you own the package, fix the malformed Requires-Dist/entry and republish.
  3. Pin to an older known-good version of the package whose metadata parses.
  4. As a last resort, install with --no-deps and manage dependencies manually (not recommended for untrusted packages).

Example fix

# before - package metadata has: Requires-Dist: foo;extra bad[syntax]
pip install brokenpkg

# after - use a release with valid metadata, or fix upstream
pip install "brokenpkg==1.2.3"  # release known to parse
Defensive patterns

Strategy: validation

Validate before calling

from packaging.requirements import Requirement, InvalidRequirement

def validate_dist_metadata_requires(requires_dist_lines):
    for line in requires_dist_lines:
        try:
            Requirement(line)
        except InvalidRequirement as e:
            raise ValueError(f"invalid Requires-Dist {line!r}: {e}") from None
# run over a wheel's METADATA before publishing or pinning

Try / catch

try:
    pip_install(req)
except InstallationError as e:
    if 'invalid metadata' in str(e):
        pin_known_good_release(req)
    else:
        raise

Prevention

When it happens

Trigger: list(dist.iter_dependencies(...)) raises InvalidRequirement inside _check_metadata_consistency. Concretely: a package whose METADATA has a Requires-Dist line with bad syntax (unbalanced extras, stray characters, invalid version specifiers, non-PEP508 markers).

Common situations: Old packages authored before strict PEP 508 enforcement; hand-edited METADATA; a sdist whose setup(install_requires=[...]) produced a malformed entry; metadata generated by an ancient setuptools that emitted non-canonical requirement strings.

Related errors

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