pypa/pip · error · BadMetadata

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

Error message

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

What it means

BadMetadata (a ValueError subclass) raised by get_dist_canonical_name() when a distribution's 'name' field cannot be derived from its .dist-info directory name and the runtime .name attribute is not a string. It signals corrupt/non-conformant package metadata rather than a user config problem.

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 d7d0d0a394)

Solutions

Reinstall the offending package from a known-good source (PyPI) to regenerate correct metadata.
Inspect the package's .dist-info directory: confirm it is named '<name>-<version>.dist-info' and that METADATA contains a 'Name' field.
Report the bad metadata to the package maintainer if it ships that way.
Remove the broken .dist-info/egg-info directory and reinstall.

Example fix

; before - mypkg.dist-info/METADATA missing Name header
Metadata-Version: 2.1
Version: 1.0

; after
Metadata-Version: 2.1
Name: mypkg
Version: 1.0

Defensive patterns

Strategy: validation

Validate before calling

import importlib.metadata, pathlib
for d in importlib.metadata.distributions():
    info = d._path  # PurePosixPath to info dir
    name = info.name if info else None
    if name and not name.endswith('.dist-info'):
        continue
    stem = name.rsplit('.dist-info',1)[0] if name else ''
    if '-' not in stem and (getattr(d,'name',None) is None or not isinstance(d.name,str)):
        print('suspicious metadata (no name):', info)

Type guard

def has_valid_name(dist) -> bool:
    import importlib.metadata
    name = getattr(dist, 'name', None)
    return isinstance(name, str) and bool(name.strip())

Try / catch

from pip._internal.metadata.importlib._compat import BadMetadata
try:
    get_dist_canonical_name(dist)
except BadMetadata as e:
    # reinstall the offending dist from a clean source
    ...

Prevention

Install packages from reputable sources to get conformant metadata.
Build wheels with current backends that emit a Name header.
Verify .dist-info directory naming follows name-version convention.
Avoid hand-editing .dist-info directories.

When it happens

Trigger: Reached in the importlib.metadata backend when parse_name_and_version_from_info_directory returns no name (info dir not named 'name-version.dist-info' or not a .dist-info at all) and dist.name is None/non-str (e.g. None because the METADATA file lacks a Name header).

Common situations: A hand-built wheel whose .dist-info directory is misnamed (no version separator) and whose METADATA omits 'Name'; a corrupted site-packages after a partial install; a third-party tool generating non-compliant metadata.

Related errors

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