pypa/pip · error · ValueError

EntryPoint must be in 'name=module:attrs [extras]' format

Error message

EntryPoint must be in 'name=module:attrs [extras]' format

What it means

Raised as ValueError in EntryPoint.parse when the input string does not match the entry point pattern regex. The expected format is 'name=module:attrs [extras]' — name and module are required, attrs and extras are optional. The regex at line 2775-2781 requires an '=' sign separating name from module.

Source

Thrown at src/pip/_vendor/pkg_resources/__init__.py:2798

        r'(:\s*(?P<attr>[\w.]+))?\s*'
        r'(?P<extras>\[.*\])?\s*$'
    )

    @classmethod
    def parse(cls, src: str, dist: Distribution | None = None):
        """Parse a single entry point from string `src`

        Entry point syntax follows the form::

            name = some.module:some.attr [extra1, extra2]

        The entry name and module name are required, but the ``:attrs`` and
        ``[extras]`` parts are optional
        """
        m = cls.pattern.match(src)
        if not m:
            msg = "EntryPoint must be in 'name=module:attrs [extras]' format"
            raise ValueError(msg, src)
        res = m.groupdict()
        extras = cls._parse_extras(res['extras'])
        attrs = res['attr'].split('.') if res['attr'] else ()
        return cls(res['name'], res['module'], attrs, extras, dist)

    @classmethod
    def _parse_extras(cls, extras_spec):
        if not extras_spec:
            return ()
        req = Requirement.parse('x' + extras_spec)
        if req.specs:
            raise ValueError
        return req.extras

    @classmethod
    def parse_group(
        cls,
        group: str,

View on GitHub (pinned to f399c37189)

Solutions

1. Verify the string matches 'name = module.path:attribute [extra1,extra2]' format with an '=' sign.
2. Check for missing or misplaced '=' — it must separate the entry name from the module path.
3. Ensure extras (if present) are in square brackets and comma-separated.
4. Use setuptools' entry_points dict/list validators instead of writing raw strings.

Example fix

// before
EntryPoint.parse('mycli mypkg.cli:main')
# ValueError: must be in 'name=module:attrs [extras]' format

// after
EntryPoint.parse('mycli = mypkg.cli:main')

import re
EP_PATTERN = re.compile(r'\s*(?P<name>.+?)\s*=\s*(?P<module>[\w.]+)\s*(:\s*(?P<attr>[\w.]+))?\s*(?P<extras>\[.*\])?\s*$')
def is_valid_entry_point_string(s: str) -> bool:
    return bool(EP_PATTERN.match(s))

import re
def is_parseable_entry_point(s: str) -> bool:
    return bool(re.match(r'^\s*.+?\s*=\s*[\w.]+\s*(:\s*[\w.]+)?\s*(\[.*\])?\s*$', s))

from pkg_resources import EntryPoint
try:
    ep = EntryPoint.parse(raw_string)
except ValueError:
    # log malformed entry point; skip it
    ep = None

When it happens

Trigger: Calling EntryPoint.parse() with a malformed string — missing '=', missing module after '=', unparseable extras brackets, or stray characters. This also fires when parsing entry_points.txt metadata that contains a malformed line.

Common situations: Hand-editing entry_points.txt with syntax errors; tools that generate entry point strings with missing '=' or wrong separators; copy-paste errors in setup.cfg/pyproject.toml [project.scripts]; whitespace or encoding issues in the metadata.

Related errors

• Error parsing entry points for {self.raw_name}: {e}
• Error parsing entry points for {self.raw_name}: {e}
• Invalid specification '%s'
• Invalid module name
• {exc}

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