pola-rs/polars · error · TypeError

`df` of type {qualified_type_name(df)!r} does not support th

Error message

`df` of type {qualified_type_name(df)!r} does not support the dataframe interchange protocol

What it means

Thrown by pl.from_dataframe when the input is neither a pl.DataFrame, nor a Polars interchange wrapper (PolarsDataFrame), and has no __dataframe__ method. The interchange protocol is the only conversion path this function supports, so any object that does not implement it is rejected up front with TypeError. Note that the whole interchange support in polars is deprecated since version 1.40.0.

Source

Thrown at py-polars/src/polars/interchange/from_dataframe.py:52

        Support for the Dataframe Interchange Protocol is deprecated.

    Parameters
    ----------
    df
        Object supporting the dataframe interchange protocol, i.e. must have implemented
        the `__dataframe__` method.
    allow_copy
        Allow memory to be copied to perform the conversion. If set to False, causes
        conversions that are not zero-copy to fail.
    """
    if isinstance(df, pl.DataFrame):
        return df
    elif isinstance(df, PolarsDataFrame):
        return df._df

    if not hasattr(df, "__dataframe__"):
        msg = f"`df` of type {qualified_type_name(df)!r} does not support the dataframe interchange protocol"
        raise TypeError(msg)

    return _from_dataframe(
        df.__dataframe__(allow_copy=allow_copy),  # type: ignore[arg-type]
        allow_copy=allow_copy,
    )


def _from_dataframe(df: InterchangeDataFrame, *, allow_copy: bool) -> DataFrame:
    chunks = []
    for chunk in df.get_chunks():
        polars_chunk = _protocol_df_chunk_to_polars(chunk, allow_copy=allow_copy)
        chunks.append(polars_chunk)

    # Handle implementations that incorrectly yield no chunks for an empty dataframe
    if not chunks:
        polars_chunk = _protocol_df_chunk_to_polars(df, allow_copy=allow_copy)
        chunks.append(polars_chunk)

View on GitHub (pinned to df599052da)

Solutions

1. Route by input type: use pl.from_pandas / pl.from_arrow / pl.from_numpy for pandas, Arrow, and numpy inputs instead of from_dataframe
2. Check hasattr(df, '__dataframe__') before calling pl.from_dataframe and handle the negative branch explicitly
3. Convert the object to Arrow first (e.g. df.to_arrow()) and call pl.from_arrow(...) which supports nested types too
4. Migrate away from pl.from_dataframe entirely - the interchange support is deprecated since polars 1.40.0

Example fix

// before
pl = __import__('polars')
df = pl.from_dataframe(some_input)  # raises TypeError if no __dataframe__

// after
if hasattr(some_input, '__dataframe__'):
    df = pl.from_dataframe(some_input)
elif 'pandas' in type(some_input).__module__:
    df = pl.from_pandas(some_input)
elif 'pyarrow' in type(some_input).__module__:
    df = pl.from_arrow(some_input)
else:
    raise TypeError(f'cannot convert {type(some_input)!r}')

def can_convert_via_interchange(df: object) -> bool:
    return hasattr(df, '__dataframe__')

from typing import Any

def supports_interchange(df: Any) -> bool:
    """Narrow: True means pl.from_dataframe(df) will pass the protocol check."""
    return hasattr(df, '__dataframe__')

try:
    out = pl.from_dataframe(df)
except TypeError as e:
    if 'does not support the dataframe interchange protocol' in str(e):
        raise TypeError(f'unsupported input {type(df)!r}; use from_pandas/from_arrow') from e
    raise

When it happens

Trigger: Calling pl.from_dataframe(...) with a Python list, dict, numpy array, generator, a Polars LazyFrame (no __dataframe__ method), or a dataframe from a library version that does not implement the protocol (e.g. old pandas, pyspark).

Common situations: Mixed-library ETL code that assumes one generic entry point works for every input; upgrading polars to >=1.40.0 where from_dataframe is deprecated; passing a lazy/streaming representation instead of an eager frame; feeding partially-initialized or wrapped dataframe objects.

Related errors

• invalid sentinel value for column of type {column_dtype}: {n
• cannot select columns using key of type {qualified_type_name
• expected {df.width} values when selecting columns by boolean
• index {key} is out of bounds for DataFrame of height {num_ro
• cannot select rows using key of type {qualified_type_name(ke

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