pypa/pip · error · BadMetadata

Bad metadata in (invalid metadata entry 'name')

Error message

Bad metadata in {dist} (invalid metadata entry 'name')

What it means

Raised as BadMetadata(dist, reason="invalid metadata entry 'name'") from get_dist_canonical_name in _compat.py:81-86. After trying to derive the name from the .dist-info directory name, pip falls back to the Distribution.name attribute; if that value is not a str (e.g. None because the METADATA 'Name' field is missing or corrupt), BadMetadata is raised.

Solutions

Reinstall the offending package from a known-good source so its METADATA 'Name' field is restored.
Manually fix or remove the corrupt .dist-info/.egg-info directory under site-packages.
If building the package yourself, ensure the build backend emits a valid 'Name' in METADATA.

Example fix

// before: METADATA file missing 'Name' header
Metadata-Version: 2.1
Version: 1.0
// after
Metadata-Version: 2.1
Name: mypkg
Version: 1.0

Defensive patterns

Strategy: try-catch

Validate before calling

// Before relying on a dist's name, sanity-check the METADATA 'Name' field:
from pip._internal.metadata.importlib._compat import get_dist_canonical_name
import importlib.metadata
for d in importlib.metadata.distributions():
    if not d.metadata.get('Name'):
        print('suspicious dist with no Name:', d)

Try / catch

from pip._internal.metadata.importlib._compat import BadMetadata
try:
    name = get_dist_canonical_name(dist)
except BadMetadata as e:
    if "invalid metadata entry 'name'" in e.reason:
        # skip or reinstall the broken dist
        ...

Prevention

Always include a valid 'Name' field in your package's METADATA.
Periodically audit installed distributions for missing metadata fields.
Reinstall packages reported by pip as having bad metadata.

When it happens

Trigger: Reading metadata for a distribution whose info directory name cannot be parsed for a name AND whose dist.name resolves to a non-string (typically None). Encountered when pip introspects a broken/installed distribution.

Common situations: A hand-edited or truncated METADATA/PKG-INFO file with no 'Name' header; a distribution installed by a buggy installer that wrote an empty name; metadata generated by an old/broken build backend.

Related errors

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

Appendix: source

Thrown at src/pip/_internal/metadata/importlib/_compat.py:86

    if suffix == ".egg-info":
        name = stem.split("-", 1)[0]
        return name, None

    return None, None


def get_dist_canonical_name(dist: importlib.metadata.Distribution) -> NormalizedName:
    """Get the distribution's normalized name.

    The ``name`` attribute is only available in Python 3.10 or later. We are
    targeting exactly that, but Mypy does not know this.
    """
    if name := parse_name_and_version_from_info_directory(dist)[0]:
        return canonicalize_name(name)

    name = cast(Any, dist).name
    if not isinstance(name, str):
        raise BadMetadata(dist, reason="invalid metadata entry 'name'")
    return canonicalize_name(name)

View on GitHub (pinned to f399c37189)