{"author":null,"author_email":"Marco Gorelli ","bugtrack_url":null,"classifiers":["License :: OSI Approved :: MIT License","Operating System :: OS Independent","Programming Language :: Python","Typing :: Typed"],"description":"# Narwhals\n\n

\n\t\n

\n\n[![PyPI version](https://badge.fury.io/py/narwhals.svg)](https://badge.fury.io/py/narwhals)\n[![Downloads](https://static.pepy.tech/badge/narwhals/month)](https://pepy.tech/project/narwhals)\n[![Trusted publishing](https://img.shields.io/badge/Trusted_publishing-Provides_attestations-bright_green)](https://peps.python.org/pep-0740/)\n[![PYPI - Types](https://img.shields.io/pypi/types/narwhals)](https://pypi.org/project/narwhals)\n\nExtremely lightweight and extensible compatibility layer between dataframe libraries!\n\n- **Full API support**: cuDF, Modin, pandas, Polars, PyArrow.\n- **Lazy-only support**: Dask, DuckDB, Ibis, PySpark, SQLFrame. Work in progress: Daft.\n\nSeamlessly support all, without depending on any!\n\n- ✅ **Just use** [a subset of **the Polars API**](https://narwhals-dev.github.io/narwhals/api-reference/), no need to learn anything new\n- ✅ **Zero dependencies**, Narwhals only uses what\n the user passes in so your library can stay lightweight\n- ✅ Separate **lazy** and eager APIs, use **expressions**\n- ✅ Support pandas' complicated type system and index, without\n either getting in the way\n- ✅ **100% branch coverage**, tested against pandas and Polars nightly builds\n- ✅ **Negligible overhead**, see [overhead](https://narwhals-dev.github.io/narwhals/overhead/)\n- ✅ Let your IDE help you thanks to **full static typing**, see [typing](https://narwhals-dev.github.io/narwhals/api-reference/typing/)\n- ✅ **Perfect backwards compatibility policy**,\n see [stable api](https://narwhals-dev.github.io/narwhals/backcompat/) for how to opt-in\n\nGet started!\n\n- [Read the documentation](https://narwhals-dev.github.io/narwhals/)\n- [Chat with us on Discord!](https://discord.gg/V3PqtB4VA4)\n- [Join our community call](https://calendar.google.com/calendar/embed?src=27ff6dc5f598c1d94c1f6e627a1aaae680e2fac88f848bda1f2c7946ae74d5ab%40group.calendar.google.com)\n- [Read the contributing guide](https://github.com/narwhals-dev/narwhals/blob/main/CONTRIBUTING.md)\n\n

Table of contents

\n\n- [Narwhals](#narwhals)\n - [Installation](#installation)\n - [Usage](#usage)\n - [Example](#example)\n - [Scope](#scope)\n - [Roadmap](#roadmap)\n - [Used by](#used-by)\n - [Sponsors and institutional partners](#sponsors-and-institutional-partners)\n - [Appears on](#appears-on)\n - [Why \"Narwhals\"?](#why-narwhals)\n\n

\n\n## Installation\n\n- pip (recommended, as it's the most up-to-date)\n ```\n pip install narwhals\n ```\n- conda-forge (also fine, but the latest version may take longer to appear)\n ```\n conda install -c conda-forge narwhals\n ```\n\n## Usage\n\nThere are three steps to writing dataframe-agnostic code using Narwhals:\n\n1. use `narwhals.from_native` to wrap a pandas/Polars/Modin/cuDF/PyArrow\n DataFrame/LazyFrame in a Narwhals class\n2. use the [subset of the Polars API supported by Narwhals](https://narwhals-dev.github.io/narwhals/api-reference/)\n3. use `narwhals.to_native` to return an object to the user in its original\n dataframe flavour. For example:\n\n - if you started with pandas, you'll get pandas back\n - if you started with Polars, you'll get Polars back\n - if you started with Modin, you'll get Modin back (and compute will be distributed)\n - if you started with cuDF, you'll get cuDF back (and compute will happen on GPU)\n - if you started with PyArrow, you'll get PyArrow back\n\n

\n\t\n\n

\n\n## Example\n\nNarwhals allows you to define dataframe-agnostic functions. For example:\n\n```python\nimport narwhals as nw\nfrom narwhals.typing import IntoFrameT\n\n\ndef agnostic_function(\n df_native: IntoFrameT,\n date_column: str,\n price_column: str,\n) -> IntoFrameT:\n return (\n nw.from_native(df_native)\n .group_by(nw.col(date_column).dt.truncate(\"1mo\"))\n .agg(nw.col(price_column).mean())\n .sort(date_column)\n .to_native()\n )\n```\n\nYou can then pass `pandas.DataFrame`, `polars.DataFrame`, `polars.LazyFrame`, `duckdb.DuckDBPyRelation`,\n`pyspark.sql.DataFrame`, `pyarrow.Table`, and more, to `agnostic_function`. In each case, no additional\ndependencies will be required, and computation will stay native to the input library:\n\n```python\nimport pandas as pd\nimport polars as pl\nfrom datetime import datetime\n\ndata = {\n \"date\": [datetime(2020, 1, 1), datetime(2020, 1, 8), datetime(2020, 2, 3)],\n \"price\": [1, 4, 3],\n}\nprint(\"pandas result:\")\nprint(agnostic_function(pd.DataFrame(data), \"date\", \"price\"))\nprint()\nprint(\"Polars result:\")\nprint(agnostic_function(pl.DataFrame(data), \"date\", \"price\"))\n```\n\n```terminal\npandas result:\n date price\n0 2020-01-01 2.5\n1 2020-02-01 3.0\n\nPolars result:\nshape: (2, 2)\n┌─────────────────────┬───────┐\n│ date ┆ price │\n│ --- ┆ --- │\n│ datetime[μs] ┆ f64 │\n╞═════════════════════╪═══════╡\n│ 2020-01-01 00:00:00 ┆ 2.5 │\n│ 2020-02-01 00:00:00 ┆ 3.0 │\n└─────────────────────┴───────┘\n```\n\nSee the [tutorial](https://narwhals-dev.github.io/narwhals/basics/dataframe/) for several examples!\n\n## Scope\n\n- Do you maintain a dataframe-consuming library?\n- Do you have a specific Polars function in mind that you would like Narwhals to have in order to make your work easier?\n\nIf you said yes to both, we'd love to hear from you!\n\n## Roadmap\n\nSee [roadmap discussion on GitHub](https://github.com/narwhals-dev/narwhals/discussions/1370)\nfor an up-to-date plan of future work.\n\n## Used by\n\nJoin the party!\n\n- [altair](https://github.com/vega/altair/)\n- [bokeh](https://github.com/bokeh/bokeh)\n- [darts](https://github.com/unit8co/darts)\n- [hierarchicalforecast](https://github.com/Nixtla/hierarchicalforecast)\n- [marimo](https://github.com/marimo-team/marimo)\n- [metalearners](https://github.com/Quantco/metalearners)\n- [panel-graphic-walker](https://github.com/panel-extensions/panel-graphic-walker)\n- [plotly](https://plotly.com)\n- [pointblank](https://github.com/posit-dev/pointblank)\n- [pymarginaleffects](https://github.com/vincentarelbundock/pymarginaleffects)\n- [py-shiny](https://github.com/posit-dev/py-shiny)\n- [rio](https://github.com/rio-labs/rio)\n- [scikit-lego](https://github.com/koaning/scikit-lego)\n- [scikit-playtime](https://github.com/koaning/scikit-playtime)\n- [tabmat](https://github.com/Quantco/tabmat)\n- [tea-tasting](https://github.com/e10v/tea-tasting)\n- [timebasedcv](https://github.com/FBruzzesi/timebasedcv)\n- [tubular](https://github.com/lvgig/tubular)\n- [Validoopsie](https://github.com/akmalsoliev/Validoopsie)\n- [vegafusion](https://github.com/vega/vegafusion)\n- [wimsey](https://github.com/benrutter/wimsey)\n\nFeel free to add your project to the list if it's missing, and/or\n[chat with us on Discord](https://discord.gg/V3PqtB4VA4) if you'd like any support.\n\n## Sponsors and institutional partners\n\nNarwhals is 100% independent, community-driven, and community-owned.\nWe are extremely grateful to the following organisations for having\nprovided some funding / development time:\n\n- [Quansight Labs](https://labs.quansight.org)\n- [Quansight Futures](https://www.qi.ventures)\n- [OpenTeams](https://www.openteams.com)\n- [POSSEE initiative](https://possee.org)\n- [BYU-Idaho](https://www.byui.edu)\n\nIf you contribute to Narwhals on your organization's time, please let us know. We'd be happy to add your employer\nto this list!\n\n## Appears on\n\nNarwhals has been featured in several talks, podcasts, and blog posts:\n\n- [Talk Python to me Podcast](https://youtu.be/FSH7BZ0tuE0)\n Ahoy, Narwhals are bridging the data science APIs\n\n- [Python Bytes Podcast](https://www.youtube.com/live/N7w_ESVW40I?si=y-wN1uCsAuJOKlOT&t=382)\n Episode 402, topic #2\n\n- [Super Data Science: ML & AI Podcast](https://www.youtube.com/watch?v=TeG4U8R0U8U) \n Narwhals: For Pandas-to-Polars DataFrame Compatibility\n\n- [Sample Space Podcast | probabl](https://youtu.be/8hYdq4sWbbQ?si=WG0QP1CZ6gkFf18b) \n How Narwhals has many end users ... that never use it directly. - Marco Gorelli\n\n- [The Real Python Podcast](https://www.youtube.com/watch?v=w5DFZbFYzCM)\n Narwhals: Expanding DataFrame Compatibility Between Libraries\n\n- [Pycon Lithuania](https://www.youtube.com/watch?v=-mdx7Cn6_6E) \n Marco Gorelli - DataFrame interoperatiblity - what's been achieved, and what comes next?\n\n- [Pycon Italy](https://www.youtube.com/watch?v=3IqUli9XsmQ) \n How you can write a dataframe-agnostic library - Marco Gorelli\n\n- [Polars Blog Post](https://pola.rs/posts/lightweight_plotting/) \n Polars has a new lightweight plotting backend\n\n- [Quansight Labs blog post (w/ Scikit-Lego)](https://labs.quansight.org/blog/scikit-lego-narwhals) \n How Narwhals and scikit-lego came together to achieve dataframe-agnosticism\n\n## Why \"Narwhals\"?\n\n[Coz they are so awesome](https://youtu.be/ykwqXuMPsoc?si=A-i8LdR38teYsos4).\n\nThanks to [Olha Urdeichuk](https://www.fiverr.com/olhaurdeichuk) for the illustration!\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"cudf, dask, dataframes, interoperability, modin, pandas, polars, pyarrow","license":null,"license_expression":null,"license_files":["LICENSE.md"],"maintainer":null,"maintainer_email":null,"name":"narwhals","package_url":"https://pypi.org/project/narwhals/","platform":null,"project_url":"https://pypi.org/project/narwhals/","project_urls":{"Bug Tracker":"https://github.com/narwhals-dev/narwhals/issues","Documentation":"https://narwhals-dev.github.io/narwhals/","Homepage":"https://github.com/narwhals-dev/narwhals","Repository":"https://github.com/narwhals-dev/narwhals"},"provides_extra":["cudf","dask","duckdb","ibis","modin","pandas","polars","pyarrow","pyspark","pyspark-connect","sqlframe"],"release_url":"https://pypi.org/project/narwhals/1.40.0/","requires_dist":["cudf>=24.10.0; extra == \"cudf\"","dask[dataframe]>=2024.8; extra == \"dask\"","duckdb>=1.0; extra == \"duckdb\"","ibis-framework>=6.0.0; extra == \"ibis\"","packaging; extra == \"ibis\"","pyarrow-hotfix; extra == \"ibis\"","rich; extra == \"ibis\"","modin; extra == \"modin\"","pandas>=0.25.3; extra == \"pandas\"","polars>=0.20.3; extra == \"polars\"","pyarrow>=11.0.0; extra == \"pyarrow\"","pyspark>=3.5.0; extra == \"pyspark\"","pyspark[connect]>=3.5.0; extra == \"pyspark-connect\"","sqlframe>=3.22.0; extra == \"sqlframe\""],"requires_python":">=3.8","summary":"Extremely lightweight compatibility layer between dataframe libraries","version":"1.40.0","yanked":false,"yanked_reason":null}

Dependency	Optional
cudf	true
dask	true
duckdb	true
ibis-framework	true
modin	true
packaging	true
pandas	true
polars	true
pyarrow	true
pyarrow-hotfix	true
pyspark	true
rich	true
sqlframe	true

Package search

narwhals

project_urls

Dependencies

All package metadata

Releases