pandas-dev/pandas · error · ImportError

'numexpr' is not installed or an unsupported version…

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() when the user explicitly requests engine='numexpr' (or leaves engine=None and numexpr is the default) but the numexpr package is either not installed or is an unsupported version. Pandas uses numexpr as an optional accelerator for query/eval; when it is unavailable, the engine cannot be used and the call aborts before parsing. The check lives in _check_engine at eval.py:74, which imports NUMEXPR_INSTALLED from pandas.core.computation.check.

Solutions

1. Install or upgrade numexpr: pip install -U numexpr (verify with python -c 'import numexpr; print(numexpr.__version__)').
2. If you cannot install numexpr, pass engine='python' explicitly to pd.eval / df.query / df.eval to skip the accelerator.
3. If numexpr is installed but the error persists, confirm the Python interpreter pandas runs under is the same one where numexpr is installed (check sys.executable and pip show numexpr).
4. For containerized deployments, add numexpr to your requirements.txt or Dockerfile RUN pip install line.

Example fix

// before
pd.eval('a + b', engine='numexpr')

// after (option A — install)
# pip install numexpr
pd.eval('a + b', engine='numexpr')

// after (option B — fall back)
pd.eval('a + b', engine='python')

try:
    import numexpr  # noqa: F401
    _numexpr_ok = True
except ImportError:
    _numexpr_ok = False

engine = 'numexpr' if _numexpr_ok else 'python'
pd.eval(expr, engine=engine)

try:
    result = pd.eval(expr, engine='numexpr')
except ImportError:
    result = pd.eval(expr, engine='python')

When it happens

Trigger: Calling pd.eval(..., engine='numexpr') or df.query(..., engine='numexpr') in an environment where numexpr is not installed or is below the minimum supported version. Also triggered indirectly when engine=None (the default) and USE_NUMEXPR is True but NUMEXPR_INSTALLED is False — though normally the default path falls back to 'python' when numexpr is absent, so the explicit engine='numexpr' request is the dominant trigger.

Common situations: Fresh virtualenvs or slim Docker images where pandas was installed without the optional numexpr dependency; CI matrices that test with and without numexpr; environments where numexpr was pip-uninstalled or an incompatible wheel was installed for the Python version in use.

Related errors

• can only assign a single expression
• Cannot assign expression output to target
• cannot assign without a target object
• cannot evaluate scalar only bool ops
• Cannot operate inplace if there is no assignment

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

Appendix: 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 3b7651241d)