pypa/pip · error · ClassNotFound

no valid {lexername} class found in {filename}

Error message

no valid {lexername} class found in {filename}

What it means

Raised by load_lexer_from_file when the file was opened and exec'd successfully but the expected class name (lexername, default 'CustomLexer') is not present in the resulting namespace.

Source

Thrown at src/pip/_vendor/pygments/lexers/__init__.py:157

    directory, which contains a Lexer class. By default, it expects the
    Lexer to be name CustomLexer; you can specify your own class name
    as the second argument to this function.

    Users should be very careful with the input, because this method
    is equivalent to running eval on the input file.

    Raises ClassNotFound if there are any problems importing the Lexer.

    .. versionadded:: 2.2
    """
    try:
        # This empty dict will contain the namespace for the exec'd file
        custom_namespace = {}
        with open(filename, 'rb') as f:
            exec(f.read(), custom_namespace)
        # Retrieve the class `lexername` from that namespace
        if lexername not in custom_namespace:
            raise ClassNotFound(f'no valid {lexername} class found in {filename}')
        lexer_class = custom_namespace[lexername]
        # And finally instantiate it with the options
        return lexer_class(**options)
    except OSError as err:
        raise ClassNotFound(f'cannot read {filename}: {err}')
    except ClassNotFound:
        raise
    except Exception as err:
        raise ClassNotFound(f'error when loading custom lexer: {err}')


def find_lexer_class_for_filename(_fn, code=None):
    """Get a lexer for a filename.

    If multiple lexers match the filename pattern, use ``analyse_text()`` to
    figure out which one is more appropriate.

    Returns None if not found.

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Confirm the exact class name in the file and pass it as lexername.
2. Name your class CustomLexer to match the default.
3. Define the class at module top level.

Example fix

# before
load_lexer_from_file('mylex.py')  # file defines SqlLexer
# after
load_lexer_from_file('mylex.py', 'SqlLexer')

import inspect
def class_in_file(filename, cls_name):
    ns = {}
    with open(filename, 'rb') as f:
        exec(f.read(), ns)
    return cls_name in ns and inspect.isclass(ns[cls_name])

from pygments.util import ClassNotFound
from pygments.lexers import load_lexer_from_file, TextLexer
try:
    lex = load_lexer_from_file(fn, name)
except ClassNotFound:
    lex = TextLexer()

When it happens

Trigger: load_lexer_from_file('mylex.py', 'MyLexer') where mylex.py defines a class with a different name, nests it, or defines none.

Common situations: Forgetting to pass the class name and relying on the default CustomLexer that the file doesn't use; class defined inside a conditional/guard; copy-pasted lexer with its original name.

Related errors

• error when loading custom lexer: {err}
• no valid {formattername} class found in {filename}
• error when loading custom formatter: {err}
• cannot read {filename}: {err}
• lex() argument must be a lexer instance, not a class

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