pola-rs/polars · error · ModuleUpgradeRequiredError

{min_err_prefix} {module_root} {min_version} or higher (foun

Error message

{min_err_prefix} {module_root} {min_version} or higher (found {mod_version})

What it means

ModuleUpgradeRequiredError (a dedicated polars.exceptions class) raised by `_import_package` when the optional module imports successfully but module.__version__ parses below the min_version the calling polars function declared. The message names the module, the required minimum, and the version actually found, so the fix is unambiguous.

Source

Thrown at py-polars/src/polars/_dependencies.py:309

    except ImportError:
        prefix = f"{err_prefix.strip(' ')} " if err_prefix else ""
        suffix = f" {err_suffix.strip(' ')}" if err_suffix else ""
        err_message = f"{prefix}'{module_name}'{suffix}.\n" + (
            install_message
            or f"Please install using the command `pip install {module_root}`."
        )
        raise ModuleNotFoundError(err_message) from None

    if min_version:
        min_version = parse_version(min_version)
        mod_version = parse_version(module.__version__)
        if mod_version < min_version:
            msg = (
                f"{min_err_prefix} {module_root} "
                f"{'.'.join(str(v) for v in min_version)} or higher"
                f" (found {'.'.join(str(v) for v in mod_version)})"
            )
            raise ModuleUpgradeRequiredError(msg)

    return module


__all__ = [
    # lazy-load rarely-used/heavy builtins (for fast startup)
    "dataclasses",
    "html",
    "json",
    "pickle",
    "subprocess",
    # lazy-load third party libs
    "altair",
    "boto3",
    "deltalake",
    "fsspec",
    "gevent",
    "great_tables",

View on GitHub (pinned to df599052da)

Solutions

Upgrade the named module to at least the stated minimum: `pip install -U 'pyarrow>=<min from message>'`
If upgrading is not allowed, pin polars to a version whose dependency floor matches your installed library
Diagnose conflicting pins with `pip check` and review the resolver output

Example fix

# before
pl.read_excel("a.xlsx")  # ModuleUpgradeRequiredError: ... fastexcel 0.10.0 or higher (found 0.7.0)

# after
# pip install -U 'fastexcel>=0.10.0'
pl.read_excel("a.xlsx")

Defensive patterns

Strategy: validation

Validate before calling

import importlib.metadata as md
from packaging.version import Version

MIN = {"pyarrow": "13.0.0"}  # floors your polars version requires
for mod, floor in MIN.items():
    if Version(md.version(mod)) < Version(floor):
        raise RuntimeError(f"{mod} >= {floor} required, found {md.version(mod)} — pip install -U {mod}")

Try / catch

from polars.exceptions import ModuleUpgradeRequiredError

try:
    pl.read_excel(path)
except ModuleUpgradeRequiredError as e:
    raise DeploymentError(f"upgrade the named dependency: {e}") from e

Prevention

Upgrade interop dependencies (pyarrow/pandas/fastexcel) together with polars, not independently
Assert minimum versions of optional deps at startup using importlib.metadata + packaging.version
Catch the specific polars.exceptions.ModuleUpgradeRequiredError to distinguish too-old from missing

When it happens

Trigger: Calling a polars API with a dependency floor (e.g. a function requiring pyarrow/numpy/pandas >= some version) while an older release of that library is installed; typical after upgrading polars but not its interop dependencies.

Common situations: Long-lived environments where polars was upgraded but pyarrow/pandas/numpy stayed pinned old; corporate baselines with aged dependencies; a new polars release raising a dependency floor for a feature you already used.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/16ce18759e96bccf. Report an issue: GitHub.