Skip to content

Installation and quick start

Installation

First, ensure you have installed UV, and make sure you have created and activated a Python 3.8+ virtual environment.

If you haven't, you can follow our setting up your environment guide. Then, run:

uv pip install narwhals

First, ensure you have created and activated a Python 3.8+ virtual environment.

Then, run:

python -m pip install narwhals

Verifying the Installation

To verify the installation, start the Python REPL and execute: 

>>> import narwhals
>>> narwhals.__version__
'1.14.1'
If you see the version number, then the installation was successful!

Quick start

Prerequisites

Please start by following the installation instructions.

To follow along with the examples which follow, please install the following (though note that they are not required dependencies - Narwhals only ever uses what the user passes in):

Simple example

Create a Python file t.py with the following content:

from __future__ import annotations

import pandas as pd
import polars as pl
import pyarrow as pa
import narwhals as nw
from narwhals.typing import IntoFrame


def my_function(df_native: IntoFrame) -> list[str]:
    df = nw.from_native(df_native)
    column_names = df.columns
    return column_names


data = {"a": [1, 2, 3], "b": [4, 5, 6]}
df_pandas = pd.DataFrame(data)
df_polars = pl.DataFrame(data)
table_pa = pa.table(data)

print("pandas output")
print(my_function(df_pandas))

print("Polars output")
print(my_function(df_polars))

print("PyArrow output")
print(my_function(table_pa))

pandas output
['a', 'b']
Polars output
['a', 'b']
PyArrow output
['a', 'b']

If you run python t.py then your output should look like the above. This is the simplest possible example of a dataframe-agnostic function - as we'll soon see, we can do much more advanced things. Let's learn about what you just did, and what Narwhals can do for you!

Note: these examples are only using pandas, Polars and PyArrow. Please see the following to find the supported libraries.