pola-rs/polars · error · ModuleNotFoundError

' ' . Please install using the command `pip install `…

Error message

{prefix}'{module_name}'{suffix}.
Please install using the command `pip install {module_root}`. (install_message may override the install hint)

What it means

`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).

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.

Example fix

// before
lf.show_graph()  # ModuleNotFoundError: ... 'graphviz' ... pip install graphviz

// after
# pip install graphviz
lf.show_graph()

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util
if importlib.util.find_spec('graphviz') is None:
    raise SystemExit('pip install graphviz')

Try / catch

try:
    result = import_optional('graphviz', err_prefix='dot-graph rendering requires')
except ModuleNotFoundError as e:
    logger.warning('graphing unavailable: %s', e)
    result = None  # degrade to text plan

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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

Appendix: source

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

    ...     err_prefix="super-important package",
    ... )  # doctest: +SKIP
    ImportError: super-important package 'definitely_a_real_module' not installed.
    Please install it using the command `pip install definitely_a_real_module`.
    """
    from polars._utils.various import parse_version
    from polars.exceptions import ModuleUpgradeRequiredError

    module_root = module_name.split(".", 1)[0]
    try:
        module = import_module(module_name)
    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",

View on GitHub (pinned to fe841f959e)