pola-rs/polars · error · TypeError

expected object supporting the PyCapsule Interface, got {qua

Error message

expected object supporting the PyCapsule Interface, got {qualified_type_name(df)!r}

What it means

TypeError raised by pl.from_dataframe when the input does not implement the DataFrame interchange/PyCapsule protocol (__dataframe__ or __arrow_c_stream__). The DataFrame Interchange Protocol requires this interface, so any other object is rejected with a message naming the offending qualified type.

Source

Thrown at py-polars/src/polars/convert/general.py:1163

    --------
    Convert a pandas dataframe to Polars.

    >>> import pandas as pd
    >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [3.0, 4.0], "c": ["x", "y"]})
    >>> pl.from_dataframe(df_pd)
    shape: (2, 3)
    ┌─────┬─────┬─────┐
    │ a   ┆ b   ┆ c   │
    │ --- ┆ --- ┆ --- │
    │ i64 ┆ f64 ┆ str │
    ╞═════╪═════╪═════╡
    │ 1   ┆ 3.0 ┆ x   │
    │ 2   ┆ 4.0 ┆ y   │
    └─────┴─────┴─────┘
    """
    if not is_pycapsule(df):
        msg = f"expected object supporting the PyCapsule Interface, got {qualified_type_name(df)!r}"
        raise TypeError(msg)

    return pycapsule_to_frame(df, rechunk=rechunk)

View on GitHub (pinned to 5d8ebabf11)

Solutions

1. Use the dedicated constructor: pl.from_pandas(df) for pandas, pl.from_arrow() for arrow objects
2. Ensure the source library implements __dataframe__ or __arrow_c_stream__ (upgrade pyarrow>=12 or the interchange package)
3. Type-check inputs before calling from_dataframe in generic pipelines

Example fix

# before
pl.from_dataframe(pandas_df)
# after
pl.from_pandas(pandas_df)

def supports_interchange(obj) -> bool:
    return hasattr(obj, '__dataframe__') or hasattr(obj, '__arrow_c_stream__')
if not supports_interchange(df):
    df = pl.from_pandas(df) if 'pandas' in type(df).__module__ else None

def is_dataframe_exportable(obj: object) -> bool:
    return hasattr(obj, '__dataframe__') or hasattr(obj, '__arrow_c_stream__')

try:
    pl.from_dataframe(obj)
except TypeError as e:
    if 'PyCapsule Interface' in str(e):
        return pl.from_pandas(obj)  # fallback for pandas inputs
    raise

When it happens

Trigger: pl.from_dataframe(pandas_df), pl.from_dataframe('path.csv'), or passing a polars DataFrame from a mismatched version lacking the capsule methods; any object failing the internal is_pycapsule check in convert/general.py:1163.

Common situations: Assuming from_dataframe accepts pandas/numpy directly (use pl.from_pandas); older pyarrow versions lacking the interchange protocol; passing Dask/Modin objects without protocol support.

Related errors

• list.to_struct() got a str instead of a list. hint: pass ['{
• `{unsupported_parameter}` parameter has no effect when using
• arr.to_struct() got a str instead of a list. hint: pass ['{f
• schema_mode='overwrite' requires mode='overwrite'
• expected type 'int | str', got {qualified_type_name(item)!r}

AI-assisted analysis of pola-rs/polars@5d8ebabf11 (2026-08-28). Data as JSON: /api/errors/1b373c65fdfca38b. Report an issue: GitHub.