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 ArrowExtensionArray.

What it means

Raised by _check_pyarrow_available() when HAS_PYARROW is False, i.e. the pyarrow package is not importable or is older than pandas' declared PYARROW_MIN_VERSION. ArrowExtensionArray and ArrowStringArray (the 'string[pyarrow]' / ArrowDtype backends) are only functional with a sufficiently recent pyarrow, so importing or constructing them without it fails fast with an ImportError rather than producing a broken object.

Source

Thrown at pandas/core/arrays/string_arrow.py:76

        AxisInt,
        Dtype,
        NpDtype,
        Scalar,
        npt,
    )

    from pandas.core.dtypes.dtypes import ExtensionDtype

    from pandas import Series


def _check_pyarrow_available() -> None:
    if not HAS_PYARROW:
        msg = (
            f"pyarrow>={PYARROW_MIN_VERSION} is required for PyArrow "
            "backed ArrowExtensionArray."
        )
        raise ImportError(msg)


def _is_string_view(typ):
    return not pa_version_under16p0 and pa.types.is_string_view(typ)


# TODO: Inherit directly from BaseStringArrayMethods. Currently we inherit from
# ObjectStringArrayMixin because we want to have the object-dtype based methods as
# fallback for the ones that pyarrow doesn't yet support


@set_module("pandas.arrays")
class ArrowStringArray(ObjectStringArrayMixin, ArrowExtensionArray, BaseStringArray):
    """
    Extension array for string data in a ``pyarrow.ChunkedArray``.

    .. warning::

View on GitHub (pinned to 71959b8cb9)

Solutions

Install or upgrade pyarrow: `pip install -U pyarrow` (or `conda install pyarrow`).
Pin pyarrow to at least pandas' PYARROW_MIN_VERSION (check `from pandas.compat import PYARROW_MIN_VERSION`).
If pyarrow is intentionally absent, fall back to the object/python string backend by using dtype='string' or dtype='string[python]' instead of 'string[pyarrow]'.
For Docker/CI, add pyarrow to the requirements file and rebuild the image.

Example fix

# before
pd.array(['a','b'], dtype='string[pyarrow]')  # ImportError if pyarrow missing
# after
# pip install pyarrow
pd.array(['a','b'], dtype='string[pyarrow]')

Defensive patterns

Strategy: validation

Validate before calling

from pandas.compat import HAS_PYARROW, PYARROW_MIN_VERSION

def require_pyarrow():
    if not HAS_PYARROW:
        raise ImportError(f'pyarrow>={PYARROW_MIN_VERSION} required; pip install pyarrow')
    import pyarrow as pa
    return pa

Type guard

from pandas.compat import HAS_PYARROW
def has_pyarrow_backend() -> bool:
    return HAS_PYARROW

Try / catch

try:
    arr = pd.array(data, dtype='string[pyarrow]')
except ImportError:
    arr = pd.array(data, dtype='string[python]')  # fallback

Prevention

Pin pyarrow>=PYARROW_MIN_VERSION in requirements.txt / pyproject.toml.
Feature-detect HAS_PYARROW before opting into Arrow backends.
Document the optional dependency in your package install extras.

When it happens

Trigger: Calling pd.array(data, dtype='string[pyarrow]'), pd.ArrowDtype(...), or pd.Series(..., dtype=pd.ArrowDtype(pa.string())) in an environment where pyarrow is missing or below the minimum. Also triggered by read_csv(..., engine='pyarrow') paths that materialize ArrowExtensionArray.

Common situations: Fresh virtualenv/conda env without pyarrow installed; CI image that pip-installs only pandas; downgrading pyarrow below the min version; deploying a slim Docker image that strips optional deps.

Related errors

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