{pfx}{name} requires {self._module_name!r} module to be inst

Error message

{pfx}{name} requires {self._module_name!r} module to be installed

What it means

polars lazy-imports heavy/optional third-party modules (pyarrow, pandas, torch, ...) through proxy modules for fast startup. If the target module is not installed, the proxy stays in place and any attribute access on it raises ModuleNotFoundError naming the exact missing module (with a prefix identifying the polars entry point that needs it, when known). The failure is lazy: it fires only when the optional feature is actually used, not at `import polars`.

Source

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

        # accessing the proxy module's attributes triggers import of the real thing
        if self._module_available:
            # import the module and return the requested attribute
            module = self._import()
            return getattr(module, name)

        # user has not installed the proxied/lazy module
        elif name == "__name__":
            return self._module_name
        elif re.match(r"^__\w+__$", name) and name != "__version__":
            # allow some minimal introspection on private module
            # attrs to avoid unnecessary error-handling elsewhere
            return None
        else:
            # all other attribute access raises a helpful exception
            pfx = self._mod_pfx.get(self._module_name, "")
            msg = f"{pfx}{name} requires {self._module_name!r} module to be installed"
            raise ModuleNotFoundError(msg) from None


def _lazy_import(module_name: str) -> tuple[ModuleType, bool]:
    """
    Lazy import the given module; avoids up-front import costs.

    Parameters
    ----------
    module_name : str
        name of the module to import, eg: "pyarrow".

    Notes
    -----
    If the requested module is not available (eg: has not been installed), a proxy
    module is created in its place, which raises an exception on any attribute
    access. This allows for import and use as normal, without requiring explicit
    guard conditions - if the module is never used, no exception occurs; if it
    is, then a helpful exception is raised.

View on GitHub (pinned to df599052da)

Solutions

Install the module named in the message, e.g. `pip install pyarrow`, or the matching extra `pip install 'polars[pandas]'`
Add the dependency to your requirements/pyproject so the env is reproducible
If you believe it is installed: confirm you are in the same interpreter/venv — `python -m pip list | grep <module>` — and that the notebook kernel matches

Example fix

# before
import polars as pl
df.to_pandas()  # ModuleNotFoundError: ... requires 'pandas' module to be installed

# after
# pip install pandas
import polars as pl
df.to_pandas()

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

required = "pyarrow"  # the module named in the error
if importlib.util.find_spec(required) is None:
    raise RuntimeError(f"{required} is required for this polars feature — pip install {required}")

Type guard

import importlib.util

def module_available(name: str) -> bool:
    """True if `name` is importable without importing it."""
    return importlib.util.find_spec(name) is not None

Try / catch

try:
    df.to_pandas()
except ModuleNotFoundError as e:
    # message names the missing module, e.g. "requires 'pandas' module to be installed"
    raise DeploymentError(f"optional dependency missing: {e}") from e

Prevention

Declare polars extras in requirements (polars[pandas], polars[pyarrow]) matching every interop feature you use
Check importlib.util.find_spec('<module>') at app startup for each optional dependency your code path needs
Validate dependencies in the deployed environment, not only in dev (same interpreter/kernel)
Treat ModuleNotFoundError from polars as a packaging bug in your env spec, not a runtime exception to swallow

When it happens

Trigger: Calling any polars API whose implementation touches an absent optional dependency and therefore reads an attribute off the proxied module — e.g. `df.to_pandas()` without pandas, arrow interop without pyarrow, `write_excel` paths without xlsxwriter — the proxy's __getattr__ raises as soon as the attribute is resolved.

Common situations: Installing plain `pip install polars` (no extras) and then using interop/I-O functions; slim Docker images where pandas/pyarrow were pruned; a dependency freeze that dropped the optional module after a cleanup pass.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/efacf622c07b3f86. Report an issue: GitHub.