pypa/pip · error · ClassNotFound

no formatter found for name

Error message

no formatter found for name {_alias!r}

What it means

Raised by get_formatter_by_name when no built-in or plugin formatter class has the given alias in its 'aliases' list. Returns ClassNotFound. The alias must match one of the entries in a formatter's aliases tuple.

Solutions

1. List available aliases via get_all_formatters() and use a registered alias.
2. Install the plugin that provides the missing formatter.
3. Use a documented alias like 'html', 'latex', 'terminal', 'terminal256'.

Example fix

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

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

def formatter_alias_exists(alias: str) -> bool:
    from pip._vendor.pygments.formatters import find_formatter_class
    return find_formatter_class(alias) is not None

from pip._vendor.pygments.util import ClassNotFound
try:
    fmt = get_formatter_by_name(alias)
except ClassNotFound:
    fmt = get_formatter_by_name('text')

When it happens

Trigger: Calling get_formatter_by_name('html5') (alias not registered), a typo, or requesting an alias only available via a plugin that isn't installed. find_formatter_class returns None at __init__.py:78.

Common situations: Typo in formatter alias in config; alias removed/renamed between pygments versions; third-party formatter plugin not installed; using the formatter's class name instead of an alias.

Related errors

• format() argument must be a formatter instance, not a class
• no formatter found for file name
• no valid class found in
• cannot read
• error when loading custom formatter

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

Appendix: 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 f399c37189)