pola-rs/polars · error · ModuleUpgradeRequiredError

or higher (found )

Error message

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

What it means

Polars raises ModuleUpgradeRequiredError when an optional dependency is present but too old for the feature you called. import_optional checks the installed version against the feature's minimum required version and fails fast instead of letting the call crash later on a missing attribute.

Solutions

Upgrade the optional dependency, e.g. `pip install -U <module_root>`, to at least the minimum version shown in the message
If upgrading is not possible, pin Polars to an older release whose minimum matches your installed dependency
Check for shadowing: `pip show <module_root>` and ensure the installed location is the environment actually in use
Recreate/refresh the venv so requirements resolve against current Polars constraints

Example fix

// before
lf.write_excel('out.xlsx')  # ModuleUpgradeRequiredError: xlsxwriter 3.0.3 found, needs 3.2+
// after
# pip install -U xlsxwriter
lf.write_excel('out.xlsx')

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.metadata as md
min_v = (3, 2, 0)  # per feature docs
cur = tuple(int(x) for x in md.version('xlsxwriter').split('.')[:3])
if cur < min_v:
    raise SystemExit(f'xlsxwriter {cur} < required {min_v}')

Type guard

def meets_min(mod_version, min_version):
    return tuple(mod_version) >= tuple(min_version)

Try / catch

try:
    lf.write_excel('out.xlsx')
except ModuleUpgradeRequiredError as e:
    print(e)  # upgrade the named module to at least the stated version

Prevention

Pin optional deps together with polars in one lockfile
Add a minimum-version check in CI before running export/report jobs
Use pip check to catch inconsistent requirement sets
Rebuild environments from the lockfile instead of upgrading packages piecemeal

When it happens

Trigger: Calling an API that lazily imports an optional dependency (activate_monitoring, display_dot_graph, to_jax, to_torch, write_excel, write_database) while the installed module (e.g. xlsxwriter, sqlalchemy, jax, torch, deltalake) is below the required minimum version.

Common situations: Pinned or frozen requirements in CI that predate Polars' bumped minimums; stale system-site packages shadowing a newer venv install; using a distro-packaged version of a library that lags behind.

Related errors

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

Appendix: 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 fe841f959e)