pypa/pip · error · InstallationError

Error parsing entry points for {self.raw_name}: {e}

Error message

Error parsing entry points for {self.raw_name}: {e}

What it means

Raised as InstallationError from Distribution.iter_entry_points in _dists.py:200-208 (importlib.metadata backend). On Python 3.15+ importlib.metadata validates entry points while parsing; a malformed entry_points.txt that raises ValueError is wrapped with the distribution's raw name so the offending package is identifiable.

Source

Thrown at src/pip/_internal/metadata/importlib/_dists.py:206

        # zipfile.Path), it can never contain any distutils scripts.
        if not isinstance(self._info_location, pathlib.Path):
            return
        for child in self._info_location.joinpath("scripts").iterdir():
            yield child.name

    def read_text(self, path: InfoPath) -> str:
        content = self._dist.read_text(str(path))
        if content is None:
            raise FileNotFoundError(path)
        return content

    def iter_entry_points(self) -> Iterable[BaseEntryPoint]:
        # importlib.metadata's EntryPoint structure satisfies BaseEntryPoint.
        try:
            return self._dist.entry_points
        except ValueError as e:
            # Python 3.15+ validates entry points while parsing.
            raise InstallationError(
                f"Error parsing entry points for {self.raw_name}: {e}"
            ) from e

    def _metadata_impl(self) -> email.message.Message:
        # From Python 3.10+, importlib.metadata declares PackageMetadata as the
        # return type. This protocol is unfortunately a disaster now and misses
        # a ton of fields that we need, including get() and get_payload(). We
        # rely on the implementation that the object is actually a Message now,
        # until upstream can improve the protocol. (python/cpython#94952)
        metadata = self._dist.metadata
        # From Python 3.15+, importlib.metadata may return None when no
        # metadata file (METADATA or PKG-INFO) exists in the distribution
        # directory. (python/cpython#132947)
        if metadata is None:
            return email.message.Message()
        return cast(email.message.Message, metadata)

    def iter_provided_extras(self) -> Iterable[NormalizedName]:

View on GitHub (pinned to f399c37189)

Solutions

  1. Reinstall the package from a version whose entry_points.txt is valid.
  2. Fix the entry_points.txt / setup() entry_points definition in the source and rebuild.
  3. Temporarily ignore the package's console scripts if they are not needed.

Example fix

// before (entry_points.txt)
[console_scripts]
mycmd
// after
[console_scripts]
mycmd = mypkg.cli:main
Defensive patterns

Strategy: try-catch

Validate before calling

// Before iterating entry points, validate entry_points.txt parses:
import configparser, io
ep = dist.read_text('entry_points.txt')
if ep:
    cp = configparser.ConfigParser()
    cp.read_string(ep)  # raises on malformed syntax

Try / catch

from pip._internal.exceptions import InstallationError
try:
    list(dist.iter_entry_points())
except InstallationError as e:
    if 'Error parsing entry points' in str(e):
        # reinstall the package or ignore its scripts
        ...

Prevention

When it happens

Trigger: Accessing iter_entry_points() on a Distribution whose entry_points.txt contains a syntactically invalid entry (e.g. missing '=', bad syntax), causing importlib.metadata's entry_points property to raise ValueError.

Common situations: A package with a hand-edited or buggy entry_points.txt; a build backend that emitted malformed entry-point definitions; running under Python 3.15+ where validation is stricter.

Related errors

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