pypa/pip · error · ClassNotFound

no valid {formattername} class found in {filename}

Error message

no valid {formattername} class found in {filename}

What it means

Raised by load_formatter_from_file when the file was opened and exec'd successfully but the expected class name (formattername, default 'CustomFormatter') is absent from the resulting namespace. The file ran, but it didn't define the class you named.

Source

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

    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
    """
    try:
        # This empty dict will contain the namespace for the exec'd file
        custom_namespace = {}
        with open(filename, 'rb') as f:
            exec(f.read(), custom_namespace)
        # Retrieve the class `formattername` from that namespace
        if formattername not in custom_namespace:
            raise ClassNotFound(f'no valid {formattername} class found in {filename}')
        formatter_class = custom_namespace[formattername]
        # And finally instantiate it with the options
        return formatter_class(**options)
    except OSError as err:
        raise ClassNotFound(f'cannot read {filename}: {err}')
    except ClassNotFound:
        raise
    except Exception as err:
        raise ClassNotFound(f'error when loading custom formatter: {err}')


def get_formatter_for_filename(fn, **options):
    """
    Return a :class:`.Formatter` subclass instance that has a filename pattern
    matching `fn`. The formatter is given the `options` at its instantiation.

    Will raise :exc:`pygments.util.ClassNotFound` if no formatter for that filename
    is found.

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Open the file and confirm the exact class name, then pass it as formattername.
2. Name your class CustomFormatter to match the default.
3. Ensure the class is defined at module top level, not nested or guarded by a runtime condition.

Example fix

# before
load_formatter_from_file('myfmt.py')  # file defines ColorFormatter
# after
load_formatter_from_file('myfmt.py', 'ColorFormatter')

import inspect
def class_in_file(filename, cls_name):
    ns = {}
    with open(filename, 'rb') as f:
        exec(f.read(), ns)
    return cls_name in ns and inspect.isclass(ns[cls_name])

from pygments.util import ClassNotFound
try:
    fmt = load_formatter_from_file(fn, name)
except ClassNotFound as e:
    # inspect message, fall back to a builtin formatter
    fmt = get_formatter_by_name('html')

When it happens

Trigger: load_formatter_from_file('myfmt.py', 'MyFormatter') where myfmt.py defines a differently-named class, defines it inside a function/conditional, or defines none at all.

Common situations: Default class name mismatch (file defines ColorFormatter but you call without specifying, expecting CustomFormatter); class defined conditionally so it isn't in module namespace at exec time; copy-paste from another formatter without renaming the class.

Related errors

• error when loading custom formatter: {err}
• cannot read {filename}: {err}
• no valid {lexername} class found in {filename}
• error when loading custom lexer: {err}
• format() argument must be a formatter instance, not a class

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