{"record":{"id":"efacf622c07b3f86","repo":"pola-rs/polars","slug":"pfx-name-requires-self-module-name-r-module","errorCode":null,"errorMessage":"{pfx}{name} requires {self._module_name!r} module to be installed","messagePattern":"(.+?)(.+?) requires (.+?) module to be installed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_dependencies.py","lineNumber":104,"sourceCode":"\n        # accessing the proxy module's attributes triggers import of the real thing\n        if self._module_available:\n            # import the module and return the requested attribute\n            module = self._import()\n            return getattr(module, name)\n\n        # user has not installed the proxied/lazy module\n        elif name == \"__name__\":\n            return self._module_name\n        elif re.match(r\"^__\\w+__$\", name) and name != \"__version__\":\n            # allow some minimal introspection on private module\n            # attrs to avoid unnecessary error-handling elsewhere\n            return None\n        else:\n            # all other attribute access raises a helpful exception\n            pfx = self._mod_pfx.get(self._module_name, \"\")\n            msg = f\"{pfx}{name} requires {self._module_name!r} module to be installed\"\n            raise ModuleNotFoundError(msg) from None\n\n\ndef _lazy_import(module_name: str) -> tuple[ModuleType, bool]:\n    \"\"\"\n    Lazy import the given module; avoids up-front import costs.\n\n    Parameters\n    ----------\n    module_name : str\n        name of the module to import, eg: \"pyarrow\".\n\n    Notes\n    -----\n    If the requested module is not available (eg: has not been installed), a proxy\n    module is created in its place, which raises an exception on any attribute\n    access. This allows for import and use as normal, without requiring explicit\n    guard conditions - if the module is never used, no exception occurs; if it\n    is, then a helpful exception is raised.","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_dependencies.py#L86-L122","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nimport polars as pl\ndf.to_pandas()  # ModuleNotFoundError: ... requires 'pandas' module to be installed\n\n# after\n# pip install pandas\nimport polars as pl\ndf.to_pandas()","handlingStrategy":"validation","validationCode":"import importlib.util\n\nrequired = \"pyarrow\"  # the module named in the error\nif importlib.util.find_spec(required) is None:\n    raise RuntimeError(f\"{required} is required for this polars feature — pip install {required}\")","typeGuard":"import importlib.util\n\ndef module_available(name: str) -> bool:\n    \"\"\"True if `name` is importable without importing it.\"\"\"\n    return importlib.util.find_spec(name) is not None","tryCatchPattern":"try:\n    df.to_pandas()\nexcept ModuleNotFoundError as e:\n    # message names the missing module, e.g. \"requires 'pandas' module to be installed\"\n    raise DeploymentError(f\"optional dependency missing: {e}\") from e","preventionTips":["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"],"tags":["dependencies","optional-deps","lazy-import","module-not-found"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}