{"record":{"id":"16ce18759e96bccf","repo":"pola-rs/polars","slug":"min-err-prefix-module-root-min-version-or-hi","errorCode":null,"errorMessage":"{min_err_prefix} {module_root} {min_version} or higher (found {mod_version})","messagePattern":"(.+?) (.+?) (.+?) or higher \\(found (.+?)\\)","errorType":"exception","errorClass":"ModuleUpgradeRequiredError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_dependencies.py","lineNumber":309,"sourceCode":"    except ImportError:\n        prefix = f\"{err_prefix.strip(' ')} \" if err_prefix else \"\"\n        suffix = f\" {err_suffix.strip(' ')}\" if err_suffix else \"\"\n        err_message = f\"{prefix}'{module_name}'{suffix}.\\n\" + (\n            install_message\n            or f\"Please install using the command `pip install {module_root}`.\"\n        )\n        raise ModuleNotFoundError(err_message) from None\n\n    if min_version:\n        min_version = parse_version(min_version)\n        mod_version = parse_version(module.__version__)\n        if mod_version < min_version:\n            msg = (\n                f\"{min_err_prefix} {module_root} \"\n                f\"{'.'.join(str(v) for v in min_version)} or higher\"\n                f\" (found {'.'.join(str(v) for v in mod_version)})\"\n            )\n            raise ModuleUpgradeRequiredError(msg)\n\n    return module\n\n\n__all__ = [\n    # lazy-load rarely-used/heavy builtins (for fast startup)\n    \"dataclasses\",\n    \"html\",\n    \"json\",\n    \"pickle\",\n    \"subprocess\",\n    # lazy-load third party libs\n    \"altair\",\n    \"boto3\",\n    \"deltalake\",\n    \"fsspec\",\n    \"gevent\",\n    \"great_tables\",","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_dependencies.py#L291-L327","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\npl.read_excel(\"a.xlsx\")  # ModuleUpgradeRequiredError: ... fastexcel 0.10.0 or higher (found 0.7.0)\n\n# after\n# pip install -U 'fastexcel>=0.10.0'\npl.read_excel(\"a.xlsx\")","handlingStrategy":"validation","validationCode":"import importlib.metadata as md\nfrom packaging.version import Version\n\nMIN = {\"pyarrow\": \"13.0.0\"}  # floors your polars version requires\nfor mod, floor in MIN.items():\n    if Version(md.version(mod)) < Version(floor):\n        raise RuntimeError(f\"{mod} >= {floor} required, found {md.version(mod)} — pip install -U {mod}\")","typeGuard":null,"tryCatchPattern":"from polars.exceptions import ModuleUpgradeRequiredError\n\ntry:\n    pl.read_excel(path)\nexcept ModuleUpgradeRequiredError as e:\n    raise DeploymentError(f\"upgrade the named dependency: {e}\") from e","preventionTips":["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"],"tags":["dependencies","version-conflict","optional-deps","upgrade"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}