pypa/pip · error · TypeError

format() argument must be a formatter instance, not a class

Error message

format() argument must be a formatter instance, not a class

What it means

Raised by pygments.format() when the formatter argument is a Formatter *subclass* rather than an *instance*. format() calls formatter.format(...); a TypeError triggers a heuristic check (is the arg a class subclassing Formatter?) and re-raises this clearer message. Mirrors the analogous lexer guard.

Solutions

1. Instantiate the formatter: format(tokens, HtmlFormatter()).
2. Use get_formatter_by_name('html') which returns an instance.
3. Pass instances, not classes, to the top-level highlight() helper.

Example fix

# before
from pip._vendor.pygments.formatters import HtmlFormatter
out = pygments.format(tokens, HtmlFormatter)
# after
out = pygments.format(tokens, HtmlFormatter())

from inspect import isclass
if isclass(formatter):
    raise TypeError('pass a formatter instance, not the class')

def is_formatter_instance(obj) -> bool:
    from pip._vendor.pygments.formatter import Formatter
    return isinstance(obj, Formatter)

try:
    out = pygments.format(tokens, formatter)
except TypeError as e:
    if 'formatter instance' in str(e):
        formatter = formatter()
        out = pygments.format(tokens, formatter)
    else:
        raise

When it happens

Trigger: Calling pygments.format(tokens, HtmlFormatter) (class) instead of pygments.format(tokens, HtmlFormatter()). The TypeError from an unbound method call triggers __init__.py:68-74.

Common situations: Passing the formatter class directly after constructing tokens manually; example code that omits the parentheses; switching from get_formatter_by_name (returns instance) to a direct class.

Related errors

• no formatter found for file name
• no formatter found for 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/9f02ebdbee56c184. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_vendor/pygments/__init__.py:72

    Format ``tokens`` (an iterable of tokens) with the formatter ``formatter``
    (a `Formatter` instance).

    If ``outfile`` is given and a valid file object (an object with a
    ``write`` method), the result will be written to it, otherwise it
    is returned as a string.
    """
    try:
        if not outfile:
            realoutfile = getattr(formatter, 'encoding', None) and BytesIO() or StringIO()
            formatter.format(tokens, realoutfile)
            return realoutfile.getvalue()
        else:
            formatter.format(tokens, outfile)
    except TypeError:
        # Heuristic to catch a common mistake.
        from pip._vendor.pygments.formatter import Formatter
        if isinstance(formatter, type) and issubclass(formatter, Formatter):
            raise TypeError('format() argument must be a formatter instance, '
                            'not a class')
        raise


def highlight(code, lexer, formatter, outfile=None):
    """
    This is the most high-level highlighting function. It combines `lex` and
    `format` in one function.
    """
    return format(lex(code, lexer), formatter, outfile)

View on GitHub (pinned to f399c37189)