pandas-dev/pandas · error · ImportError

pyarrow>={PYARROW_MIN_VERSION} is required for PyArrow backe

Error message

pyarrow>={PYARROW_MIN_VERSION} is required for PyArrow backed StringArray.

What it means

StringDtype.__init__ raises ImportError when storage='pyarrow' is requested but pyarrow is not installed at or above PYARROW_MIN_VERSION (the HAS_PYARROW flag is False). This is an ImportError rather than ValueError because the root cause is a missing optional dependency, distinguishing it from a bad argument.

Source

Thrown at pandas/core/arrays/string_.py:216

        storage: str | None = None,
        na_value: libmissing.NAType | float = libmissing.NA,
    ) -> None:
        # infer defaults
        if storage is None:
            storage = config["mode"]["string_storage"]
            if storage == "auto":
                if HAS_PYARROW:
                    storage = "pyarrow"
                else:
                    storage = "python"

        # validate options
        if storage not in {"python", "pyarrow"}:
            raise ValueError(
                f"Storage must be 'python' or 'pyarrow'. Got {storage} instead."
            )
        if storage == "pyarrow" and not HAS_PYARROW:
            raise ImportError(
                f"pyarrow>={PYARROW_MIN_VERSION} is required for PyArrow "
                "backed StringArray."
            )

        if isinstance(na_value, float) and np.isnan(na_value):
            # when passed a NaN value, always set to np.nan to ensure we use
            # a consistent NaN value (and we can use `dtype.na_value is np.nan`)
            na_value = np.nan
        elif na_value is not libmissing.NA:
            raise ValueError(f"'na_value' must be np.nan or pd.NA, got {na_value}")

        self._storage = cast("str", storage)
        self._na_value = na_value

    def __repr__(self) -> str:
        storage = "" if self.storage == "pyarrow" else "storage='python', "
        return f"<StringDtype({storage}na_value={self._na_value})>"

View on GitHub (pinned to 71959b8cb9)

Solutions

Install or upgrade pyarrow: pip install -U pyarrow.
Fall back to python storage: StringDtype(storage='python') or dtype='string[python]'.
Pin pyarrow>=PYARROW_MIN_VERSION in your requirements file.

Example fix

// before (pyarrow not installed)
ser = pd.Series(['a','b'], dtype='string[pyarrow]')

// after
pip install pyarrow
ser = pd.Series(['a','b'], dtype='string[pyarrow]')

Defensive patterns

Strategy: try-catch

Validate before calling

from pandas.compat import HAS_PYARROW

storage = 'pyarrow' if HAS_PYARROW else 'python'
dtype = pd.StringDtype(storage=storage)

Type guard

from pandas.compat import HAS_PYARROW

def pyarrow_available() -> bool:
    return HAS_PYARROW

Try / catch

try:
    dtype = pd.StringDtype(storage='pyarrow')
except ImportError:
    dtype = pd.StringDtype(storage='python')

Prevention

Declare pyarrow in requirements.txt or pyproject for any code using string[pyarrow].
Feature-detect HAS_PYARROW before requesting pyarrow storage.
Provide a python-storage fallback in environments where pyarrow is optional.

When it happens

Trigger: Calling StringDtype(storage='pyarrow'), pd.array(data, dtype='string[pyarrow]'), pd.Series(data, dtype='string[pyarrow]'), or pd.read_csv(..., dtype_backend='pyarrow') in an environment where pyarrow is not installed or is too old.

Common situations: Fresh virtualenv without pyarrow; minimal CI images; downgrading pyarrow below the minimum; deploying to a slim container that omitted the optional dependency.

Related errors

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/bc7d9a164cbfd58d. Report an issue: GitHub.