Narwhals

Warnings

• gotcha Narwhals is a compatibility layer and does not provide dataframe functionality itself. You must install the underlying dataframe libraries (e.g., `pandas`, `polars`, `pyarrow`) separately for Narwhals to function with those backends. Not installing them will lead to `ModuleNotFoundError` or `TypeError` when `from_native` is used.
  Fix: Install the desired backend libraries, e.g., `pip install pandas polars pyarrow`.
• breaking The main `narwhals` namespace may undergo breaking changes, deprecations, or API shifts in new releases. For critical library development requiring long-term stability, prefer `import narwhals.stable.v1 as nw_stable`. This stable API is promised to never change or remove public functions. Future stable versions (e.g., `v2`, `v3`) will be introduced if breaking changes are necessary.
  Fix: For production code or libraries, use `import narwhals.stable.v1 as nw` and adhere to its API. For experimentation, the main `narwhals` namespace is acceptable.
• gotcha Narwhals implements a *subset* of the Polars API. Not all Polars functions, arguments, or behaviors are necessarily supported or identically replicated across all backends. Complex or less common Polars operations might not be available or might behave differently in specific backend implementations. Always consult the official Narwhals API completeness documentation.
  Fix: Refer to the Narwhals documentation for supported API elements. If a specific Polars feature is critical and not supported, you may need to handle that backend natively or contribute to Narwhals.
• gotcha Narwhals preserves the eager/lazy execution model of the underlying dataframe. If you pass a lazy frame (e.g., Polars LazyFrame, Dask DataFrame), operations remain lazy. Explicitly call `.collect()` when an eager result is required, especially before operations like `.shape` or `.pivot()`, which necessitate materializing the data. Failing to do so can lead to errors or unexpected behavior.
  Fix: Identify points in your code where eager computation is implicitly or explicitly needed and call `.collect()` on your Narwhals LazyFrame. Alternatively, use `eager_only=True` in `nw.from_native` if you always expect an eager frame.
• deprecated External library deprecations can affect Narwhals. For example, DuckDB 1.5 deprecated `fetch_arrow_table`. While Narwhals strives to adapt, relying on specific backend versions might expose you to these upstream changes. This is particularly relevant for `when/then` conditions, `join` operations, and null value handling across different backends, which have seen several fixes in recent versions.
  Fix: Keep Narwhals updated to benefit from fixes addressing upstream deprecations and inconsistencies. Thoroughly test your code across different backend versions and with various null value scenarios.

Install

• pip install narwhals Install Narwhals

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

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)