pola-rs/polars · error · ModuleNotFoundError

{pfx}{name} requires '{module_name}' module to be installed

Error message

{pfx}{name} requires '{module_name}' module to be installed

What it means

ImportError raised by a lazy module proxy (__getattr__ on the proxy class) in _dependencies.py: user code accessed attribute {name} of an optional dependency (e.g. polars.delimited, polars.string_cache) whose backing module {module_name} is not installed. Accessing any real attribute triggers the import; only dunder introspection attributes are allowed through.

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 9b5d73fd00)

Solutions

1. Install the missing module: pip install <module_name> (or the extra, e.g. pip install 'polars[extra]').

Example fix

pip install pandas pyarrow

When it happens

Trigger: Calling a function guarded by an optional dependency that is not installed.

Common situations: See trigger scenarios.

AI-assisted analysis of pola-rs/polars@9b5d73fd00 (2026-08-19). Data as JSON: /api/errors/4480fd69b0155392. Report an issue: GitHub.