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 as TypeError by pygments.format() when the formatter argument is a Formatter *class* instead of an *instance*. format() calls formatter.format(tokens, outfile); with the class this raises TypeError, which the heuristic detects (issubclass(formatter, Formatter)) and re-raises with this message.

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 d7d0d0a394)

Solutions

1. Instantiate the formatter: pass HtmlFormatter() to format().
2. Use pygments.formatters.get_formatter_by_name('html') to get a ready instance.
3. Verify the variable holds an instance before calling format/highlight.

Example fix

# before
from pygments import format
from pygments.formatters import HtmlFormatter
out = format(tokens, HtmlFormatter)  # TypeError

# after
out = format(tokens, HtmlFormatter())

from pygments.formatter import Formatter
if isinstance(formatter, type) and issubclass(formatter, Formatter):
    raise TypeError('pass a formatter instance, not the class')
pygments.format(tokens, formatter)

def is_formatter_instance(obj) -> bool:
    from pygments.formatter import Formatter
    return not isinstance(obj, type) and isinstance(obj, Formatter)

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

When it happens

Trigger: Calling pygments.format(tokens, HtmlFormatter) (class) instead of pygments.format(tokens, HtmlFormatter()). The except-TypError branch recognizes a Formatter subclass and raises the clearer error.

Common situations: Forgetting parentheses when constructing the formatter, or passing the class directly to highlight()/format().

Related errors

• lex() argument must be a lexer instance, not a class
• {self.__class__.__name__!r} used without bound function
• filter {filtername!r} not found
• no formatter found for name {_alias!r}
• no valid {formattername} class found in {filename}

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