pandas-dev/pandas · error · KeyError

Invalid engine ' ' passed, valid engines are

Error message

Invalid engine '{engine}' passed, valid engines are {valid_engines}

What it means

Raised by _check_engine when the `engine` argument passed to pd.eval / DataFrame.eval / DataFrame.query is not in the ENGINES registry (currently {'python', 'numexpr'}). The check is a KeyError so callers wrapping eval see a dictionary-style lookup failure. After the registry check, requesting 'numexpr' without numexpr installed raises ImportError instead.

Solutions

1. Use one of the valid engines printed in the message (typically 'python' or 'numexpr').
2. Omit engine= to accept the default (numexpr if installed, else python).
3. For 'numexpr', ensure the package is installed: pip install numexpr.

Example fix

// before
pd.eval('a + b', engine='numpy')
// after
pd.eval('a + b', engine='python')  # or omit engine=

valid = {'python', 'numexpr'}
if engine not in valid:
    raise ValueError(f'engine={engine!r}; choose from {valid}')
result = pd.eval(expr, engine=engine)

def is_valid_engine(name: str) -> bool:
    return name in {'python', 'numexpr'}

When it happens

Trigger: pd.eval('1+1', engine='rust'); df.query('a > 0', engine='numpy'); passing engine=None is fine (defaults), but a non-existent name raises.

Common situations: Typos ('numexpr' misspelled); copy-pasted snippets naming a removed/future engine; version drift where an engine was renamed.

Related errors

• cannot evaluate scalar only bool ops
• Function " " does not support keyword arguments
• Invalid function call
• keyword error in function call
• N-dimensional objects, where N > 2, are not supported with…

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/4de4e78c3d0e888d. Report an issue: GitHub.

Appendix: source

Thrown at pandas/core/computation/eval.py:67

    KeyError
      * If an invalid engine is passed.
    ImportError
      * If numexpr was requested but doesn't exist.

    Returns
    -------
    str
        Engine name.
    """
    from pandas.core.computation.check import NUMEXPR_INSTALLED
    from pandas.core.computation.expressions import USE_NUMEXPR

    if engine is None:
        engine = "numexpr" if USE_NUMEXPR else "python"

    if engine not in ENGINES:
        valid_engines = list(ENGINES.keys())
        raise KeyError(
            f"Invalid engine '{engine}' passed, valid engines are {valid_engines}"
        )

    # TODO: validate this in a more general way (thinking of future engines
    # that won't necessarily be import-able)
    # Could potentially be done on engine instantiation
    if engine == "numexpr" and not NUMEXPR_INSTALLED:
        raise ImportError(
            "'numexpr' is not installed or an unsupported version. Cannot use "
            "engine='numexpr' for query/eval if 'numexpr' is not installed"
        )

    return engine


def _check_parser(parser: str) -> None:
    """
    Make sure a valid parser is passed.

View on GitHub (pinned to 3b7651241d)