{"record":{"id":"b46024313dcb8fb2","repo":"pola-rs/polars","slug":"prefix-module-name-suffix-please-install-using-the-command","errorCode":null,"errorMessage":"{prefix}'{module_name}'{suffix}.\nPlease install using the command `pip install {module_root}`. (install_message may override the install hint)","messagePattern":"(.+?)'(.+?)'(.+?)\\.\nPlease install using the command `pip install (.+?)`\\. \\(install_message may override the install hint\\)","errorType":"exception","errorClass":"ModuleNotFoundError","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/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/_dependencies.py#L280-L316","documentation":"`import_optional` imports an optional dependency and raises `ModuleNotFoundError` with a tailored message when the module is missing: the caller-supplied prefix/suffix around the module name plus an install hint (`pip install <module_root>`, or a custom `install_message`). The message is composed at `_dependencies.py:298` from `err_prefix`/`err_suffix`/`install_message` parameters, so the text varies per call site (e.g. jax, torch, dot-graph, excel, database writers).","triggerScenarios":"Calling APIs that declare optional deps without them installed: `LazyFrame.show_graph`/`display_dot_graph` (missing `graphviz`), `to_jax`/`to_torch` (missing `jax`/`torch`), `write_excel` (missing `xlsxwriter`), `write_database` (missing `sqlalchemy`), `activate_monitoring` (missing perf module).","commonSituations":"Converting DataFrames to ML frameworks in a slim environment; plotting query plans without graphviz installed; writing to Excel or a database from a base `polars` install without extras.","solutions":["Install the named module via the hint in the message, e.g. `pip install graphviz` / `pip install 'polars[output]'` or the relevant extra.","If the message's install hint is wrong for your package manager, use the custom `install_message` by importing `import_optional` yourself with the right instruction.","Guard feature usage at runtime: `from polars.dependencies import torch_available` (or `import_optional`) and degrade gracefully when absent."],"exampleFix":"// before\nlf.show_graph()  # ModuleNotFoundError: ... 'graphviz' ... pip install graphviz\n\n// after\n# pip install graphviz\nlf.show_graph()","handlingStrategy":"try-catch","validationCode":"import importlib.util\nif importlib.util.find_spec('graphviz') is None:\n    raise SystemExit('pip install graphviz')","typeGuard":null,"tryCatchPattern":"try:\n    result = import_optional('graphviz', err_prefix='dot-graph rendering requires')\nexcept ModuleNotFoundError as e:\n    logger.warning('graphing unavailable: %s', e)\n    result = None  # degrade to text plan","preventionTips":["Install the extra named in the error message before using jax/torch/graphviz/excel/database APIs.","Probe availability with `importlib.util.find_spec` or `polars.dependencies.*_available` first.","Keep optional features behind flags or graceful fallbacks in user-facing code."],"tags":["python","polars","optional-dependency","modulenotfounderror","installation"],"backgroundTag":"missing-optional-dependency","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}