{"record":{"id":"6ef4140c66cf292b","repo":"pola-rs/polars","slug":"prefix-module-name-suffix-please-install-us","errorCode":null,"errorMessage":"{prefix}'{module_name}'{suffix}.\nPlease install using the command `pip install {module_root}`.","messagePattern":"(.+?)'(.+?)'(.+?)\\.\nPlease install using the command `pip install (.+?)`\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_dependencies.py","lineNumber":298,"sourceCode":"    ...     err_prefix=\"super-important package\",\n    ... )  # doctest: +SKIP\n    ImportError: super-important package 'definitely_a_real_module' not installed.\n    Please install it using the command `pip install definitely_a_real_module`.\n    \"\"\"\n    from polars._utils.various import parse_version\n    from polars.exceptions import ModuleUpgradeRequiredError\n\n    module_root = module_name.split(\".\", 1)[0]\n    try:\n        module = import_module(module_name)\n    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\",","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_dependencies.py#L280-L316","documentation":"Raised by polars' internal `_import_package` helper: a function that requires an optional third-party library calls import_module() and, on ImportError, re-raises ModuleNotFoundError with the exact module name and the `pip install <root-package>` command that provides it. Like the proxy-module error, it fires only when the optional code path actually runs, and it always tells you the root package to install.","triggerScenarios":"Using optional I/O or interop features without their dependency: reading Excel (fastexcel/xlsxwriter), database/deltalake connectors, pandas conversion helpers — each polars function declares the module it needs and routes the import through this helper.","commonSituations":"Base polars install without extras; code that gained a new `read_excel`/`write_excel`/database call without updating requirements; notebooks where the dependency was installed into a different kernel.","solutions":["Run the install command from the message verbatim, e.g. `pip install fastexcel`","Declare the polars extra(s) in requirements (e.g. `polars[excel]`, `polars[pandas]`) so optional deps ship with the env","Verify the import resolves in the same interpreter: `python -c \"import fastexcel\"`"],"exampleFix":"# before\npl.read_excel(\"sheet.xlsx\")  # ModuleNotFoundError: 'fastexcel' ... pip install fastexcel\n\n# after\n# pip install fastexcel\npl.read_excel(\"sheet.xlsx\")","handlingStrategy":"validation","validationCode":"import importlib.util\n\n# e.g. before pl.read_excel / write_excel\ndeps = {\"fastexcel\": \"read_excel\", \"xlsxwriter\": \"write_excel\"}\nmissing = [m for m in deps if importlib.util.find_spec(m) is None]\nif missing:\n    raise RuntimeError(\"missing optional deps: \" + \" \".join(f\"pip install {m}\" for m in missing))","typeGuard":null,"tryCatchPattern":"try:\n    pl.read_excel(path)\nexcept ModuleNotFoundError as e:\n    # the message already contains the exact `pip install <pkg>` command\n    log.error(\"dependency missing: %s\", e)\n    raise","preventionTips":["Keep a mapping in your project of polars features -> optional modules and assert them at startup","Use polars extras rather than ad-hoc installs so environments are reproducible","Smoke-test every I/O path in CI with the same dependency set as production"],"tags":["dependencies","optional-deps","module-not-found","packaging"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}