Narwhals em Python 2026: Guia Prático

Atualizado: 24 de agosto de 2026

O Narwhals é uma biblioteca leve e sem dependências que oferece uma API unificada e estável para escrever código Python compatível ao mesmo tempo com Pandas, Polars, PyArrow, Modin, cuDF e Dask, sem duplicação e sem penalidade de performance. Se você mantém uma biblioteca que aceita DataFrames de usuários (ou uma pipeline interna que precisa consumir formatos heterogêneos), o Narwhals resolve o problema numa tarde de trabalho. Neste guia atualizado para 2026, mostro os padrões que uso em produção depois de migrar dois pipelines de enriquecimento (Bronze para Silver) para a API do Narwhals 1.x.

• Narwhals 1.x (lançado em maio de 2024) oferece garantias de estabilidade semelhantes ao PEP 440. Nenhuma mudança de breaking até 2.0.
• Zero dependências obrigatórias. O Narwhals importa apenas o backend que você já tem instalado (Pandas, Polars, PyArrow, Modin, cuDF ou Dask).
• A API é modelada a partir do Polars, então quem já conhece pl.col() e expressões encadeadas escreve Narwhals nativamente.
• Adotado em produção por Altair 5.4+, Plotly Express, scikit-lego, marimo, formulaic e tubular. Não é experimental.
• Diferente do Ibis, o Narwhals não é uma camada SQL: ele preserva execução eager ou lazy do backend nativo, sem materializar dados desnecessariamente.
• Custo típico de migração de uma biblioteca de 3.000 linhas: 2 a 4 dias, com ganho imediato de compatibilidade com o Polars e cuDF.

O que é o Narwhals em Python?

O Narwhals é uma camada de compatibilidade que traduz uma única API (inspirada no Polars) para as operações nativas de cada backend DataFrame suportado. Você escreve nw.col("valor").sum() uma vez, e a mesma expressão executa contra Pandas 2.x, Polars 1.x, PyArrow 17+, Modin 0.32+, cuDF 25.02+ ou Dask 2025.1+, aproveitando o motor de execução nativo de cada um sem conversões intermediárias.

Diferentemente de tentativas anteriores como o descontinuado DataFrame Interchange Protocol, o Narwhals não força uma representação comum em memória. Ele age como um tradutor de expressões. Quando você chama .filter(), o Narwhals emite df[mask] para Pandas, df.filter() para Polars e pc.filter() para PyArrow. Cada backend recebe a chamada idiomática que sabe otimizar.

O projeto é mantido por Marco Gorelli (também mantenedor do Pandas e do Polars) e por uma comunidade ativa. A versão 1.0 foi lançada em 22 de maio de 2024 estabelecendo garantias formais de estabilidade, e a série 1.x continua a receber releases mensais. A última que verifiquei antes de escrever este artigo foi a 1.24 (agosto de 2026), com suporte a expressões de window e over().

Por que usar Narwhals em 2026?

Então, a pergunta certa em 2026 não é "pandas ou polars?". É "como escrevo código que sobrevive a ambos, e ao próximo backend que vier?". Nos últimos dois anos vi três forças convergirem: bibliotecas de visualização (Altair, plotly, seaborn 0.14) precisando aceitar DataFrames de qualquer origem; equipes de dados adotando Polars em novos pipelines enquanto mantêm código Pandas legado; e a explosão de cuDF em pipelines RAPIDS para cargas GPU. Sem uma camada como o Narwhals, cada biblioteca acaba com três implementações paralelas, o que vira um pesadelo de manutenção.

Honestamente, foi só quando bati com esse problema na prática que caiu a ficha. No time em que trabalho, migramos o validador Bronze para Silver de um pipeline de enriquecimento de transações para Narwhals em fevereiro de 2026. O código original tinha ramos if isinstance(df, pd.DataFrame) espalhados em 14 lugares. Depois da migração, sobrou uma função com @nw.narwhalify e o mesmo teste de contrato roda contra Pandas (produção legada), Polars (nova ingestão) e PyArrow (leitura de Parquet direta do S3). O tempo total de migração foi 3 dias, incluindo testes.

Bibliotecas que já anunciaram Narwhals como camada oficial de compatibilidade em 2025 e 2026: Altair 5.4+, Plotly Express 6.0+, scikit-lego 0.9+, marimo, formulaic 1.0+, tubular 2.0+, hierarchicalforecast 3.0+ e py-shiny. Se você contribui para qualquer uma delas, provavelmente já usa Narwhals sem saber.

Instalação e primeiros passos

A instalação é minimalista. O Narwhals não puxa nenhum backend obrigatório, respeitando o que você já tem no ambiente:

pip install narwhals

# opcional: instalar backends se ainda não tiver
pip install "narwhals[pandas,polars,pyarrow]"

Um primeiro exemplo canônico, uma função de agregação que aceita qualquer DataFrame e retorna o mesmo tipo:

import narwhals as nw

@nw.narwhalify
def receita_media_por_categoria(df):
    return (
        df.group_by("categoria")
          .agg(nw.col("valor").mean().alias("ticket_medio"))
          .sort("ticket_medio", descending=True)
    )

# Funciona com qualquer backend:
import pandas as pd
import polars as pl

pdf = pd.DataFrame({"categoria": ["A", "A", "B"], "valor": [10, 20, 30]})
pldf = pl.DataFrame({"categoria": ["A", "A", "B"], "valor": [10, 20, 30]})

print(receita_media_por_categoria(pdf))   # retorna pandas.DataFrame
print(receita_media_por_categoria(pldf))  # retorna polars.DataFrame

O decorator @nw.narwhalify aplica from_native aos argumentos e to_native ao retorno, e o backend original é preservado. Nenhuma conversão de memória acontece; o Narwhals apenas embrulha o objeto original com um wrapper leve.

O padrão from_native / to_native

O decorator é conveniente, mas em código de biblioteca prefiro o padrão explícito. Ele deixa claro para o leitor onde termina o mundo Narwhals e começa o mundo nativo:

import narwhals as nw
from narwhals.typing import IntoFrame, FrameT

def resumo_estatistico(df_native: IntoFrame) -> IntoFrame:
    df: FrameT = nw.from_native(df_native)

    resultado = df.select(
        nw.col("valor").mean().alias("media"),
        nw.col("valor").std().alias("desvio"),
        nw.col("valor").quantile(0.95, interpolation="linear").alias("p95"),
        nw.len().alias("n_linhas"),
    )

    return nw.to_native(resultado)

Note os tipos IntoFrame (aceita qualquer DataFrame nativo) e FrameT (garantia de tipo Narwhals). Esses hints fazem o mypy e o pyright entenderem seu contrato. Em produção, essa clareza vale mais do que a economia de duas linhas do decorator.

Para operações lazy, o Narwhals expõe LazyFrame equivalente. Se o backend for Polars, você ganha o motor lazy real; se for Pandas, o Narwhals executa eager por baixo mas mantém a interface consistente:

lazy = nw.from_native(pldf).lazy()
resultado = (
    lazy.filter(nw.col("valor") > 15)
        .group_by("categoria")
        .agg(nw.col("valor").sum())
        .collect()
)

API estável vs. main: qual escolher?

Desde a 1.0, o Narwhals mantém dois namespaces: import narwhals as nw (a API principal, que evolui com features novas) e import narwhals.stable.v1 as nw (congelada em maio de 2024 e imutável até 2.0). Para bibliotecas publicadas no PyPI que serão consumidas por terceiros, use sempre narwhals.stable.v1. Assim, uma nova release do Narwhals nunca quebra o seu código.

import narwhals.stable.v1 as nw  # garantia até 2.0

@nw.narwhalify
def minha_funcao(df):
    return df.select(nw.col("x") * 2)

Para código de aplicação interno onde você controla o versionamento, use narwhals direto e aproveite features novas. Esse padrão de dupla-API é copiado do modelo do módulo typing padrão e funciona bem: nunca tive uma quebra de contrato desde que adotamos stable.v1 em março de 2025.

Narwhals vs. Ibis: qual a diferença?

Essa é a pergunta que mais recebo. Ambos oferecem "uma API para múltiplos backends", mas resolvem problemas diferentes. O Ibis é uma camada de compilação para SQL: traduz expressões para DuckDB, BigQuery, Snowflake, Postgres e Clickhouse. O Narwhals é uma camada de compatibilidade para DataFrames em memória, como Pandas, Polars, PyArrow e cuDF.

Aspecto	Narwhals	Ibis
Alvo principal	Bibliotecas Python que aceitam DataFrames de usuários	Análise em bancos de dados / data warehouses
Backends	Pandas, Polars, PyArrow, Modin, cuDF, Dask	DuckDB, BigQuery, Snowflake, Postgres, Clickhouse, Trino, Spark, +20
Modelo de execução	Preserva eager/lazy do backend nativo	Sempre lazy, compila para SQL
Overhead	Quase zero (wrapper fino de expressões)	Compilação SQL + round-trip ao backend
Dependências	Zero obrigatórias	SQLGlot + drivers
Caso ideal	Autor de biblioteca visualização/ML/validação	Analista escrevendo queries portáteis

Na prática, os dois são complementares. No pipeline que gerencio, o Ibis roda queries no Snowflake para trazer dados agregados para memória; o Narwhals então processa esses DataFrames independente de virem como Pandas ou PyArrow. Não escolha entre eles: entenda que resolvem camadas diferentes do stack.

Casos reais de produção em 2026

Três padrões que vi funcionar bem em código de produção nos últimos 12 meses:

1. Validador de contratos com Pydantic + Narwhals

Combinamos Pydantic 2 para validação de contratos com Narwhals para inspeção estrutural do DataFrame. O Narwhals expõe df.schema uniformemente, e não importa se o input veio como Pandas ou Polars:

import narwhals.stable.v1 as nw
from pydantic import BaseModel

class ContratoTransacao(BaseModel):
    colunas_obrigatorias: list[str] = ["id", "valor", "timestamp"]

def validar(df_native, contrato: ContratoTransacao):
    df = nw.from_native(df_native)
    faltando = set(contrato.colunas_obrigatorias) - set(df.columns)
    if faltando:
        raise ValueError(f"Colunas faltando: {faltando}")
    return df_native

2. Feature engineering multi-backend

Bibliotecas como scikit-lego passaram a aceitar Polars e PyArrow via Narwhals a partir da versão 0.9. Isso permite que um transformer treinado num DataFrame Pandas seja aplicado num Polars DataFrame na inferência, sem conversão intermediária, que é onde memória e latência costumam explodir.

3. Substituição gradual de Pandas em pipelines legados

Se você mantém uma base grande em Pandas mas quer migrar para Polars sem big-bang, envolva as funções de transformação em @nw.narwhalify. O código continua rodando com Pandas; depois, mude só a origem dos dados para Polars e as funções continuam funcionando. Fizemos isso com um pipeline de 12.000 linhas em três sprints, sem downtime.

Erros comuns e armadilhas

Alguns tropeços recorrentes que vi (e cometi):

• Esquecer que .to_pandas() materializa. Chamar .to_pandas() num DataFrame que veio como Polars força cópia completa dos dados. Use apenas na borda quando for interoperar com biblioteca que não suporta Narwhals.
• Assumir suporte a índices tipo Pandas. O Narwhals segue o modelo do Polars: não há índices. Se seu código depende de df.set_index(), você precisa refatorar para group_by ou join.
• Usar __getitem__ com máscara booleana. Escreva df.filter(nw.col("x") > 0) em vez de df[df["x"] > 0], já que o segundo padrão só funciona em alguns backends.
• Não fixar a versão do Narwhals para bibliotecas. Mesmo com stable.v1, novos backends podem ter comportamento sutil diferente. Fixe narwhals>=1.20,<2 no pyproject.toml.
• Ignorar diferenças de null. Pandas mistura NaN e None; Polars é estrito. O Narwhals expõe nw.col("x").is_null() uniforme, mas o comportamento downstream pode variar em edge cases (eu tomei um susto com isso ao migrar um filtro anti-join numa terça-feira às 23h).

Benchmarks: qual o overhead real?

Fiz medições em um pipeline de agregação com 50 milhões de linhas (Parquet, ~2 GB em memória) rodando num container com limite de 8 GB, ou seja, o cenário que descrevo no meu perfil sobre "Polars em containers com restrições de memória". Os números abaixo são médias de 10 execuções na minha máquina de testes (AWS c7i.2xlarge, Python 3.13, agosto de 2026):

Backend	Nativo (s)	Via Narwhals (s)	Overhead
Polars 1.14	1.82	1.86	+2.2%
Pandas 2.3	14.4	14.7	+2.1%
PyArrow 17	3.91	4.02	+2.8%
cuDF 25.02 (GPU T4)	0.42	0.44	+4.7%

O overhead do Narwhals é dominado pela alocação de wrappers de expressão em Python, algo irrelevante para qualquer workload real. Em cargas < 10 ms, o overhead pode chegar a 15 ou 20%, mas nesse regime o gargalo está em outro lugar. Confirme na página oficial do projeto no GitHub, onde eles publicam benchmarks CI a cada release.

Perguntas frequentes

O Narwhals substitui o Pandas ou o Polars?

Não. O Narwhals é uma camada de compatibilidade que usa Pandas ou Polars por baixo, então você continua precisando de um backend real instalado. Ele resolve o problema de "código único, múltiplos backends", não o problema de "qual DataFrame usar".

O Narwhals está pronto para produção em 2026?

Sim. A versão 1.0 saiu em maio de 2024 com garantia formal de estabilidade e o projeto é adotado por Altair, Plotly Express, scikit-lego e outras bibliotecas de grande escala. Use narwhals.stable.v1 para máxima segurança em código de biblioteca.

Qual a diferença entre Narwhals e o DataFrame Interchange Protocol?

O DataFrame Interchange Protocol define apenas conversão em memória entre bibliotecas, sem operações. O Narwhals oferece uma API completa de expressões que executa nativamente em cada backend, sem forçar cópia de dados nem conversão intermediária.

O Narwhals funciona com Spark ou Dask?

Dask tem suporte completo desde a versão 1.10. Para Spark, o suporte via PySpark DataFrame está em beta em 2026 e cobre a maioria das operações comuns, mas ainda não todas as expressões de janela. Verifique a matriz de compatibilidade nas docs oficiais antes de adotar.

Posso usar Narwhals em cargas GPU com cuDF?

Sim, cuDF 25.02+ é totalmente suportado. Você escreve o mesmo código Narwhals e ele delega para o motor GPU do cuDF em NVIDIA. Essa é a forma mais fácil hoje de fazer uma biblioteca CPU/GPU-agnóstica em Python.