pandas-dev/pandas · error · ImportError

'numexpr' is not installed or an unsupported version. Cannot

Error message

'numexpr' is not installed or an unsupported version. Cannot use engine='numexpr' for query/eval if 'numexpr' is not installed

What it means

Raised by _check_engine (pandas/core/computation/eval.py:75) as an ImportError when engine='numexpr' is explicitly requested but the numexpr package is either not installed or is an unsupported version (checked via NUMEXPR_INSTALLED from pandas.core.computation.check). The numexpr backend is optional and must be installed separately; pandas refuses to fall back silently to the python engine when the user explicitly chose numexpr.

Source

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

        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.

    Parameters
    ----------
    parser : str

    Raises
    ------
    KeyError

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Install numexpr: `pip install numexpr` (or conda install numexpr) with a compatible version.
2. If numexpr is unavailable, switch the call to `engine='python'` or omit engine to let pandas pick.
3. If you control the environment, ensure numexpr is in your pinned dependencies and USE_NUMEXPR is not disabled.

Example fix

# before
df.query('x > 0', engine='numexpr')  # numexpr missing

# after (option A)
pip install numexpr
# after (option B)
df.query('x > 0', engine='python')

def engine_or_python(engine='numexpr'):
    try:
        import numexpr  # noqa: F401
    except ImportError:
        if engine == 'numexpr':
            return 'python'
    return engine

df.query('x > 0', engine=engine_or_python())

def numexpr_available() -> bool:
    try:
        import numexpr  # noqa: F401
        from pandas.core.computation.check import NUMEXPR_INSTALLED
        return bool(NUMEXPR_INSTALLED)
    except ImportError:
        return False

try:
    result = df.query('x > 0', engine='numexpr')
except ImportError:
    result = df.query('x > 0', engine='python')

When it happens

Trigger: `df.query('x > 0', engine='numexpr')` in an environment without numexpr installed, or with an incompatible numexpr version. CI/containers built from a minimal pandas install. Auto-detection only defaults to numexpr when USE_NUMEXPR is true, but an explicit request bypasses fallback.

Common situations: Missing dependency in requirements.txt/environment.yml, pinned incompatible numexpr version, deploying a slim Docker image, or numexpr disabled via pandas option USE_NUMEXPR.

Related errors

• Variables in expression "{expr}" overlap with builtins: ({s}
• pyarrow>={PYARROW_MIN_VERSION} is required for PyArrow backe
• Invalid engine '{engine}' passed, valid engines are {valid_e
• expr cannot be an empty string
• The '@' prefix is only supported by the pandas parser

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/514435db2f2a7dfb. Report an issue: GitHub.