pypa/pip · error · ClassNotFound

filter {filtername!r} not found

Error message

filter {filtername!r} not found

What it means

Raised as ClassNotFound by get_filter_by_name() when the requested filter name is neither in the built-in FILTERS dict nor provided by a pygments plugin (find_plugin_filters). The message echoes the offending name so the caller can correct it.

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

Solutions

1. Check the available names via list(get_all_filters()) and use the exact name.
2. Correct the typo (e.g. 'codetags' is the built-in name, not 'codetag').
3. Install the plugin package that provides the filter, or implement a custom filter via @simplefilter.

Example fix

# before
from pygments.filters import get_filter_by_name
f = get_filter_by_name('codetag')  # ClassNotFound

# after
from pygments.filters import get_all_filters
assert 'codetags' in get_all_filters()
f = get_filter_by_name('codetags')

from pygments.filters import find_filter_class, get_all_filters
if filtername not in get_all_filters():
    raise ValueError(f'unknown filter {filtername!r}; available: {sorted(get_all_filters())}')
get_filter_by_name(filtername)

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

try:
    f = get_filter_by_name(name)
except ClassNotFound as e:
    if 'filter' in str(e) and 'not found' in str(e):
        # pick a default or list available filters
        from pygments.filters import get_all_filters
        raise SystemExit(f'choose from {sorted(get_all_filters())}')
    raise

When it happens

Trigger: Calling get_filter_by_name('codetag') with a misspelled name; find_filter_class returns None for both the built-in table and plugins, so ClassNotFound is raised.

Common situations: Typo in the filter name, referencing a filter from a plugin that is not installed, or a name that changed across Pygments versions.

Related errors

• {self.__class__.__name__!r} used without bound function
• lex() argument must be a lexer instance, not a class
• format() argument must be a formatter instance, not a class
• excclass option is not an exception class
• no formatter found for name {_alias!r}

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