pypa/pip · error · ClassNotFound

no formatter found for file name

Error message

no formatter found for file name {fn!r}

What it means

Raised by get_formatter_for_filename when no built-in or plugin formatter's filename glob matches the given filename. Each formatter declares a 'filenames' tuple of glob patterns (e.g. '*.html'); if none match the basename, ClassNotFound is raised at __init__.py:137. Matching uses fnmatch translation.

Solutions

1. Check get_all_formatters() filenames patterns and map your extension to one explicitly.
2. Use get_formatter_by_name with an explicit alias instead of filename guessing.
3. Install a plugin formatter that handles the extension.

Example fix

# before
fmt = get_formatter_for_filename('output.svgz')
# after
fmt = get_formatter_by_name('svg')

from pip._vendor.pygments.formatters import get_all_formatters
globs = [pat for cls in get_all_formatters() for pat in cls.filenames]
import fnmatch
if not any(fnmatch.fnmatch(os.path.basename(fn), g) for g in globs):
    raise ValueError(f'no formatter pattern matches {fn}')

def filename_has_formatter(fn: str) -> bool:
    from pip._vendor.pygments.formatters import get_all_formatters
    import fnmatch, os
    b = os.path.basename(fn)
    return any(fnmatch.fnmatch(b, g) for cls in get_all_formatters() for g in cls.filenames)

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

When it happens

Trigger: Calling get_formatter_for_filename('data.xyz') where no formatter claims the '.xyz' extension; passing a name with no extension; a custom extension not registered to any formatter.

Common situations: Highlighting an unusual file type with no registered formatter; missing extension; case mismatch (patterns are case-sensitive on some platforms); plugin for that extension not installed.

Related errors

• format() argument must be a formatter instance, not a class
• 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/6a4ff78466388e3a. Report an issue: GitHub.

Appendix: source

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

    """
    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.
    """
    fn = basename(fn)
    for modname, name, _, filenames, _ in FORMATTERS.values():
        for filename in filenames:
            if _fn_matches(fn, filename):
                if name not in _formatter_cache:
                    _load_formatters(modname)
                return _formatter_cache[name](**options)
    for _name, cls in find_plugin_formatters():
        for filename in cls.filenames:
            if _fn_matches(fn, filename):
                return cls(**options)
    raise ClassNotFound(f"no formatter found for file name {fn!r}")


class _automodule(types.ModuleType):
    """Automatically import formatters."""

    def __getattr__(self, name):
        info = FORMATTERS.get(name)
        if info:
            _load_formatters(info[0])
            cls = _formatter_cache[info[1]]
            setattr(self, name, cls)
            return cls
        raise AttributeError(name)


oldmod = sys.modules[__name__]
newmod = _automodule(__name__)
newmod.__dict__.update(oldmod.__dict__)

View on GitHub (pinned to f399c37189)