{"record":{"id":"1b373c65fdfca38b","repo":"pola-rs/polars","slug":"expected-object-supporting-the-pycapsule-interface","errorCode":null,"errorMessage":"expected object supporting the PyCapsule Interface, got {qualified_type_name(df)!r}","messagePattern":"expected object supporting the PyCapsule Interface, got (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/convert/general.py","lineNumber":1163,"sourceCode":"    --------\n    Convert a pandas dataframe to Polars.\n\n    >>> import pandas as pd\n    >>> df_pd = pd.DataFrame({\"a\": [1, 2], \"b\": [3.0, 4.0], \"c\": [\"x\", \"y\"]})\n    >>> pl.from_dataframe(df_pd)\n    shape: (2, 3)\n    ┌─────┬─────┬─────┐\n    │ a   ┆ b   ┆ c   │\n    │ --- ┆ --- ┆ --- │\n    │ i64 ┆ f64 ┆ str │\n    ╞═════╪═════╪═════╡\n    │ 1   ┆ 3.0 ┆ x   │\n    │ 2   ┆ 4.0 ┆ y   │\n    └─────┴─────┴─────┘\n    \"\"\"\n    if not is_pycapsule(df):\n        msg = f\"expected object supporting the PyCapsule Interface, got {qualified_type_name(df)!r}\"\n        raise TypeError(msg)\n\n    return pycapsule_to_frame(df, rechunk=rechunk)\n","sourceCodeStart":1145,"sourceCodeEnd":1166,"githubUrl":"https://github.com/pola-rs/polars/blob/5d8ebabf11caea54a5c29178a64a058762f49766/py-polars/src/polars/convert/general.py#L1145-L1166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the dedicated constructor: pl.from_pandas(df) for pandas, pl.from_arrow() for arrow objects","Ensure the source library implements __dataframe__ or __arrow_c_stream__ (upgrade pyarrow>=12 or the interchange package)","Type-check inputs before calling from_dataframe in generic pipelines"],"exampleFix":"# before\npl.from_dataframe(pandas_df)\n# after\npl.from_pandas(pandas_df)","handlingStrategy":"type-guard","validationCode":"def supports_interchange(obj) -> bool:\n    return hasattr(obj, '__dataframe__') or hasattr(obj, '__arrow_c_stream__')\nif not supports_interchange(df):\n    df = pl.from_pandas(df) if 'pandas' in type(df).__module__ else None","typeGuard":"def is_dataframe_exportable(obj: object) -> bool:\n    return hasattr(obj, '__dataframe__') or hasattr(obj, '__arrow_c_stream__')","tryCatchPattern":"try:\n    pl.from_dataframe(obj)\nexcept TypeError as e:\n    if 'PyCapsule Interface' in str(e):\n        return pl.from_pandas(obj)  # fallback for pandas inputs\n    raise","preventionTips":["Use from_pandas/from_arrow for those specific sources","Require pyarrow>=12 or interchange-capable libs in dependencies","Validate inputs at ingestion boundaries"],"tags":["python","polars","dataframe-protocol","pycapsule","type-error"],"backgroundTag":"dataframe-interchange-unsupported-object","analyzedSha":"5d8ebabf11caea54a5c29178a64a058762f49766","analyzedAt":"2026-08-28T18:02:35.179Z","contentChangedAt":"2026-08-28T18:02:35.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}