pola-rs/polars · error · ModuleNotFoundError

pyarrow>=8.0.0 is required for `to_pandas(use_pyarrow_extens

Error message

pyarrow>=8.0.0 is required for `to_pandas(use_pyarrow_extension_array=True)`

What it means

Raised as ModuleNotFoundError by DataFrame.to_pandas(use_pyarrow_extension_array=True) when pyarrow is not installed at all (polars' core is rust and does not require pyarrow). The extension-array path needs pyarrow both for ArrowDtype and for the actual zero-copy-ish conversion, so its complete absence is fatal for this option. The sibling branch (pyarrow present but <8.0) raises ModuleUpgradeRequiredError instead.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:2622

        foo           int64[pyarrow]
        bar          double[pyarrow]
        ham    large_string[pyarrow]
        dtype: object
        """
        if self.width == 0:
            return pd.DataFrame(index=range(self.height))

        if use_pyarrow_extension_array:
            if parse_version(pd.__version__) < (1, 5):
                msg = f'pandas>=1.5.0 is required for `to_pandas("use_pyarrow_extension_array=True")`, found Pandas {pd.__version__!r}'
                raise ModuleUpgradeRequiredError(msg)
            if not _PYARROW_AVAILABLE or parse_version(pa.__version__) < (8, 0):
                msg = "pyarrow>=8.0.0 is required for `to_pandas(use_pyarrow_extension_array=True)`"
                if _PYARROW_AVAILABLE:
                    msg += f", found pyarrow {pa.__version__!r}."
                    raise ModuleUpgradeRequiredError(msg)
                else:
                    raise ModuleNotFoundError(msg)

        # handle Object columns separately (Arrow does not convert them correctly)
        if Object in self.dtypes:
            return self._to_pandas_with_object_columns(
                use_pyarrow_extension_array=use_pyarrow_extension_array, **kwargs
            )

        return self._to_pandas_without_object_columns(
            self, use_pyarrow_extension_array=use_pyarrow_extension_array, **kwargs
        )

    def _to_pandas_with_object_columns(
        self,
        *,
        use_pyarrow_extension_array: bool,
        **kwargs: Any,
    ) -> pd.DataFrame:
        # Find which columns are of type pl.Object, and which aren't:

View on GitHub (pinned to df599052da)

Solutions

  1. Install pyarrow: `pip install 'pyarrow>=8'`
  2. If pyarrow is intentionally excluded, use the default conversion `df.to_pandas()`
  3. Add pyarrow to the project's locked dependencies if you rely on extension-array output

Example fix

# before (no pyarrow installed)
pdf = df.to_pandas(use_pyarrow_extension_array=True)  # ModuleNotFoundError

# after
# pip install 'pyarrow>=8'
pdf = df.to_pandas(use_pyarrow_extension_array=True)
Defensive patterns

Strategy: validation

Validate before calling

def pyarrow_available(min_version=(8, 0)) -> bool:
    try:
        import pyarrow as pa
    except ImportError:
        return False
    return parse_version(pa.__version__) >= min_version

pdf = df.to_pandas(use_pyarrow_extension_array=True) if pyarrow_available() else df.to_pandas()

Try / catch

try:
    pdf = df.to_pandas(use_pyarrow_extension_array=True)
except ModuleNotFoundError as e:
    if 'pyarrow>=8.0.0' in str(e):
        pdf = df.to_pandas()  # numpy/object dtypes instead of arrow-backed
    else:
        raise

Prevention

When it happens

Trigger: `df.to_pandas(use_pyarrow_extension_array=True)` in an environment without pyarrow — e.g. slim docker images, polars-only installs where pyarrow was never added, or CI matrices that skip optional deps. The guard is `if not _PYARROW_AVAILABLE or parse_version(pa.__version__) < (8, 0)` with the ModuleNotFoundError taken in the else.

Common situations: Minimal container images that deliberately exclude pyarrow; new contributors running without requirements fully installed; optional-dependency install (`pip install polars`) rather than `polars[pyarrow]`-style extras in teams that rely on them.

Related errors

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