Narwhals

Common errors

Warnings

Install compatibility verified last tested: 2026-05-12

Imports

• narwhals

  import narwhals as nw

• IntoFrameT

  from narwhals.typing import IntoFrameT

  Useful for type hinting dataframe-agnostic functions

• stable.v1

  import narwhals.stable.v1 as nw_stable

  Use this for long-term API stability in library development, though the main 'narwhals' namespace is more actively developed for new features.

Quickstart stale last tested: 2026-04-23

This quickstart demonstrates how to write a dataframe-agnostic function using Narwhals. The function `process_data` accepts any supported native dataframe type (e.g., pandas DataFrame, Polars DataFrame) via `nw.from_native`, applies a group-by and aggregation operation using Narwhals' Polars-like API, and then converts the result back to the original native dataframe type using `to_native()`.

import narwhals as nw
import pandas as pd
import polars as pl
from narwhals.typing import IntoFrameT

def process_data(df_native: IntoFrameT) -> IntoFrameT:
    df = nw.from_native(df_native)
    result = (
        df.group_by(nw.col('category'))
        .agg(nw.col('value').mean().alias('mean_value'))
        .sort('mean_value', descending=True)
    )
    return result.to_native()

# Example with pandas
pd_df = pd.DataFrame({'category': ['A', 'B', 'A', 'C'], 'value': [10, 20, 15, 25]})
pd_result = process_data(pd_df)
print('Pandas Result:')
print(pd_result)

# Example with polars
pl_df = pl.DataFrame({'category': ['A', 'B', 'A', 'C'], 'value': [10, 20, 15, 25]})
pl_result = process_data(pl_df)
print('\nPolars Result:')
print(pl_result)