pypa/pip · error · ClassNotFound

filter not found

Error message

filter {filtername!r} not found

What it means

Raised by get_filter_by_name when the requested filter name is neither in the built-in FILTERS dict nor found among registered plugin filters. Returns ClassNotFound, the standard pygments exception for missing lookups. Callers must pass a recognized filter name.

Solutions

1. Check get_all_filters() for the exact set of available names and use one of those.
2. Install the plugin package that registers the missing filter.
3. Upgrade pygments if the filter was added in a newer release.
4. Correct typos (names are case-sensitive and lowercase, e.g. 'tokenreplace').

Example fix

# before
f = get_filter_by_name('RaiseOnError')
# after
f = get_filter_by_name('raiseonerror')

from pip._vendor.pygments.filters import find_filter_class
if find_filter_class(name) is None:
    raise ValueError(f'unknown filter: {name}')

def filter_exists(name: str) -> bool:
    from pip._vendor.pygments.filters import find_filter_class
    return find_filter_class(name) is not None

from pip._vendor.pygments.util import ClassNotFound
try:
    f = get_filter_by_name(name)
except ClassNotFound:
    f = None  # or a default filter

When it happens

Trigger: Calling get_filter_by_name('nonexistent') or a misspelled name; calling it before plugin entry points are installed; requesting a filter that exists only in a newer pygments version.

Common situations: Typo in a filter name in config; using a filter name from documentation for a different pygments version; referencing a third-party filter whose plugin isn't installed.

Related errors

• excclass option is not an exception class
• used without bound function
• format() argument must be a formatter instance, not a class
• lex() argument must be a lexer instance, not a class
• no formatter found for file name

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

Appendix: source

Thrown at src/pip/_vendor/pygments/filters/__init__.py:42

    if filtername in FILTERS:
        return FILTERS[filtername]
    for name, cls in find_plugin_filters():
        if name == filtername:
            return cls
    return None


def get_filter_by_name(filtername, **options):
    """Return an instantiated filter.

    Options are passed to the filter initializer if wanted.
    Raise a ClassNotFound if not found.
    """
    cls = find_filter_class(filtername)
    if cls:
        return cls(**options)
    else:
        raise ClassNotFound(f'filter {filtername!r} not found')


def get_all_filters():
    """Return a generator of all filter names."""
    yield from FILTERS
    for name, _ in find_plugin_filters():
        yield name


def _replace_special(ttype, value, regex, specialttype,
                     replacefunc=lambda x: x):
    last = 0
    for match in regex.finditer(value):
        start, end = match.start(), match.end()
        if start != last:
            yield ttype, value[last:start]
        yield specialttype, replacefunc(value[start:end])
        last = end

View on GitHub (pinned to f399c37189)