pola-rs/polars · error · ModuleNotFoundError

requires module to be installed

Error message

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

What it means

When an optional dependency module is not installed, `_ModuleAvailableProxy.__getattr__` raises `ModuleNotFoundError` naming the attribute you accessed and the missing module (optionally with a package-name prefix for extras like `fsspec[http]`). It converts what would be an opaque `AttributeError` into an actionable install hint. Accessing `__path__`/availability checks returns None instead; all other attributes raise.

Solutions

  1. Install the missing module named in the message, e.g. `pip install fastexcel` or the matching extra `pip install 'polars[excel]'`.
  2. Check availability first with `polars.dependencies.<name>_available` (or `_lazy_import`) before using optional features.
  3. If you own the calling code, add the dependency to requirements/setup extras so environments are provisioned consistently.

Example fix

// before
import polars as pl
df.write_excel('out.xlsx')  # ModuleNotFoundError: write_excel requires 'xlsxwriter'

// after
# pip install 'polars[excel]'
import polars as pl
df.write_excel('out.xlsx')
Defensive patterns

Strategy: fallback

Validate before calling

import polars.dependencies as pdep
if not pdep.fastexcel_available:
    raise SystemExit('pip install fastexcel')

Try / catch

try:
    df.write_excel('out.xlsx')
except ModuleNotFoundError as e:
    logger.warning('optional dep missing, skipping export: %s', e)
    # fallback: df.write_csv('out.csv')

Prevention

When it happens

Trigger: Accessing any attribute of a not-installed optional module proxy, e.g. `polars.dependencies.xlsx_available` proxies or `mod.xlsxwrite...` calls when `xlsx2csv`/`fastexcel`/`pyarrow` etc. are absent; calling `df.write_excel()` without the xlsx extras installed and hitting the proxied import path.

Common situations: Fresh environments without optional extras (`pip install polars` instead of `polars[all]`); Docker images trimmed of optional deps; code paths for excel/databases/plotting that need `xlsx2csv`, `deltalake`, `fsspec`, `sqlalchemy`, etc.

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/efacf622c07b3f86. Report an issue: GitHub.

Appendix: 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 fe841f959e)