pypa/pip · error · ClassNotFound

no formatter found for name {_alias!r}

Error message

no formatter found for name {_alias!r}

What it means

Raised by get_formatter_by_name when find_formatter_class returns None, meaning no builtin or plugin formatter has the supplied alias in its aliases list. This is the primary lookup-by-name failure for formatters.

Source

Thrown at src/pip/_vendor/pygments/formatters/__init__.py:80

            if name not in _formatter_cache:
                _load_formatters(module_name)
            return _formatter_cache[name]
    for _, cls in find_plugin_formatters():
        if alias in cls.aliases:
            return cls


def get_formatter_by_name(_alias, **options):
    """
    Return an instance of a :class:`.Formatter` subclass that has `alias` in its
    aliases list. The formatter is given the `options` at its instantiation.

    Will raise :exc:`pygments.util.ClassNotFound` if no formatter with that
    alias is found.
    """
    cls = find_formatter_class(_alias)
    if cls is None:
        raise ClassNotFound(f"no formatter found for name {_alias!r}")
    return cls(**options)


def load_formatter_from_file(filename, formattername="CustomFormatter", **options):
    """
    Return a `Formatter` subclass instance loaded from the provided file, relative
    to the current directory.

    The file is expected to contain a Formatter class named ``formattername``
    (by default, CustomFormatter). Users should be very careful with the input, because
    this method is equivalent to running ``eval()`` on the input file. The formatter is
    given the `options` at its instantiation.

    :exc:`pygments.util.ClassNotFound` is raised if there are any errors loading
    the formatter.

    .. versionadded:: 2.2
    """

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Spell the alias correctly (e.g. 'html', 'terminal', 'terminal16m', 'latex').
2. List valid names via pygments.formatters.FORMATTERS or list(get_all_formatters()).
3. Install the plugin package that registers the missing formatter.

Example fix

# before
fmt = get_formatter_by_name('htm')
# after
fmt = get_formatter_by_name('html')

from pygments.formatters import find_formatter_class
if find_formatter_class(alias) is None:
    raise ValueError(f'unknown formatter alias {alias!r}')

from pygments.formatters import find_formatter_class
def is_known_formatter(alias):
    return find_formatter_class(alias) is not None

from pygments.util import ClassNotFound
try:
    fmt = get_formatter_by_name(alias)
except ClassNotFound:
    fmt = get_formatter_by_name('terminal')  # safe fallback

When it happens

Trigger: Calling get_formatter_by_name('htm') (typo), get_formatter_by_name('pdf') (no such formatter), or any alias not registered by builtin FORMATTERS or setuptools entry-point plugins.

Common situations: Typo in the formatter alias read from CLI/config; depending on a formatter provided by a plugin that isn't installed; formatter renamed/removed across pygments versions.

Related errors

• no formatter found for file name {fn!r}
• format() argument must be a formatter instance, not a class
• filter {filtername!r} not found
• no valid {formattername} class found in {filename}
• cannot read {filename}: {err}

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