pypa/pip · error · DistlibException

Invalid specification '%s'

Error message

Invalid specification '%s'

What it means

Raised by get_export_entry() when parsing an entry-point specification. ENTRY_RE did not match the string, but the string contains '[' or ']', which indicates a malformed flags/bracket section. A DistlibException 'Invalid specification' is raised to tell the caller the entry-point string is not in the expected 'name = module[:attr] [flags]' form.

Source

Thrown at src/pip/_vendor/distlib/util.py:729

                      and self.flags == other.flags)
        return result

    __hash__ = object.__hash__


ENTRY_RE = re.compile(
    r'''(?P<name>([^\[]\S*))
                      \s*=\s*(?P<callable>(\w+)([:\.]\w+)*)
                      \s*(\[\s*(?P<flags>[\w-]+(=\w+)?(,\s*\w+(=\w+)?)*)\s*\])?
                      ''', re.VERBOSE)


def get_export_entry(specification):
    m = ENTRY_RE.search(specification)
    if not m:
        result = None
        if '[' in specification or ']' in specification:
            raise DistlibException("Invalid specification "
                                   "'%s'" % specification)
    else:
        d = m.groupdict()
        name = d['name']
        path = d['callable']
        colons = path.count(':')
        if colons == 0:
            prefix, suffix = path, None
        else:
            if colons != 1:
                raise DistlibException("Invalid specification "
                                       "'%s'" % specification)
            prefix, suffix = path.split(':')
        flags = d['flags']
        if flags is None:
            if '[' in specification or ']' in specification:
                raise DistlibException("Invalid specification "
                                       "'%s'" % specification)

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Rewrite the spec in the canonical form 'name = pkg.module:attr [flag1, flag2]' with balanced brackets.
2. Remove the brackets entirely if no flags are needed.
3. Ensure there are no stray '[' or ']' elsewhere in the string.

Example fix

// before
get_export_entry('cli = mypkg.cli:main [console)')
// after
get_export_entry('cli = mypkg.cli:main [console]')

import re
ENTRY_RE = re.compile(r'(?P<name>([^\[]\S*))\s*=\s*(?P<callable>(\w+)([:\.]\w+)*)\s*(\[\s*(?P<flags>[\w-]+(=\w+)?(,\s*\w+(=\w+)?)*)\s*\])?')
def safe_get_entry(spec):
    if ('[' in spec or ']' in spec) and not ENTRY_RE.search(spec):
        raise ValueError('malformed entry-point flags: %r' % spec)
    from distlib.util import get_export_entry
    return get_export_entry(spec)

from distlib.util import get_export_entry, DistlibException
try:
    entry = get_export_entry(spec)
except DistlibException as e:
    if 'Invalid specification' in str(e):
        report_bad_entry_point(spec)
    else:
        raise

When it happens

Trigger: get_export_entry('foo = bar.baz [bad flag]') (brackets present but regex fails), get_export_entry('foo[] = bar'), or any entry_points spec where brackets appear but the overall grammar does not match ENTRY_RE.

Common situations: Hand-editing entry_points in setup.cfg/pyproject.toml and mismatching brackets, trailing spaces inside brackets, or flags with illegal characters.

Related errors

• Ill-formed name/version string: '%s'
• invalid version: %s
• invalid constraint: %s
• invalid requirement: %s
• unexpected trailing data: %s

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