pola-rs/polars · error · ModuleUpgradeRequiredError

pandas>=1.5.0 is required for `to_pandas("use_pyarrow_extens

Error message

pandas>=1.5.0 is required for `to_pandas("use_pyarrow_extension_array=True")`, found Pandas {pd.__version__!r}

What it means

Raised as ModuleUpgradeRequiredError by DataFrame.to_pandas(use_pyarrow_extension_array=True) when the installed pandas is older than 1.5.0. Arrow-backed extension dtypes in pandas (int64[pyarrow], large_string[pyarrow], ...) were only made usable at scale in the 1.5 series, so polars gates the option on that version and reports the found version in the message. It fires before any conversion work starts.

Source

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

        >>> df.to_pandas(use_pyarrow_extension_array=True)
            foo   bar   ham
        0     1   6.0  <NA>
        1     2  <NA>     b
        2  <NA>   8.0     c
        >>> _.dtypes
        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
        )

View on GitHub (pinned to df599052da)

Solutions

  1. Upgrade pandas: `pip install -U 'pandas>=1.5'` (or `conda install 'pandas>=1.5'`)
  2. If you cannot upgrade, drop the flag: `df.to_pandas()` (object/numpy dtypes, still copies)
  3. Pin `pandas>=1.5` in your project requirements so environments can't regress

Example fix

# before (pandas 1.4)
pdf = df.to_pandas(use_pyarrow_extension_array=True)  # ModuleUpgradeRequiredError

# after
# pip install -U 'pandas>=1.5'
pdf = df.to_pandas(use_pyarrow_extension_array=True)
Defensive patterns

Strategy: validation

Validate before calling

import pandas as pd
from polars._utils.version import parse_version

if parse_version(pd.__version__) < (1, 5):
    pdf = df.to_pandas()  # fallback: no extension arrays
else:
    pdf = df.to_pandas(use_pyarrow_extension_array=True)

Try / catch

try:
    pdf = df.to_pandas(use_pyarrow_extension_array=True)
except ModuleUpgradeRequiredError as e:
    if 'pandas>=1.5.0' in str(e):
        pdf = df.to_pandas()  # or abort and demand the upgrade
    else:
        raise

Prevention

When it happens

Trigger: `df.to_pandas(use_pyarrow_extension_array=True)` in an environment with pandas < 1.5.0 — e.g. pinned legacy environments, base conda envs, or old distro python. The check is `parse_version(pd.__version__) < (1, 5)`.

Common situations: Corporate environments with pinned old pandas; freshly created venvs where pandas was installed as an old transitive dependency; CI images built years ago; mixing polars (modern) with pandas (legacy) for interop.

Related errors

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