Polars · Module

.list.eval

Applies a Polars expression to every element of each list and returns the results as lists. Use pl.element() to reference the current element; optional inner parallelism is available but should not be enabled indiscriminately.

How it works

Use this expression namespace method when each row contains a variable-length list and an expression must be applied independently to every element. Reference the current element with pl.element(); the result remains a list-valued expression rather than being automatically unwrapped.

Syntax

Expr.list.eval(expr: Expr, *, parallel: bool = False) → Expr

Parameters

Name	Type	Description
`expr`	`Expr`	Expression to run. Use pl.element() to reference each list item.
`parallel`	`bool = False`	Whether to run expression evaluation in parallel; defaults to False.

Returns

Expr

Key points

The method evaluates one Polars expression independently over the elements of every list in the input expression.
Use pl.element() inside the supplied expression to refer to the current item being processed.
Compared with list.agg, list.eval keeps the evaluated values nested instead of automatically exploding them.
Use arr.eval when the input uses the fixed-size Array datatype rather than variable-length List values.

Common mistakes

Setting parallel=True is not automatically beneficial.
Avoid enabling per-list parallelism inside a group-by aggregation, where groups are already processed in parallel.

Example: Rank elements in each list

import polars as pl

df = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]})
result = df.with_columns(
    pl.concat_list("a", "b")
    .list.eval(pl.element().rank())
    .alias("rank")
)
print(result)

Ranks the values in each row's constructed list.

When to use it

Transform or rank nested values

A dataframe has multiple values collected into one list per row, and each value needs ranking, casting, string matching, or another Polars expression.

Clean list-column contents

A list column requires per-element validation or normalization while retaining one list output per input row.

Process List columns

A computation must run over variable-length lists in expression context rather than fixed-size arrays.

Interview questions

QWhat does Expr.list.eval do?

It applies a Polars expression to every element of each list and returns an Expr. Inside the expression, pl.element() identifies the current list item.

Follow-up: How would you obtain scalar aggregation results instead? Use list.agg, which evaluates an expression and automatically explodes suitable single-value results.

QWhen should parallel be enabled?

The default is parallel=False. parallel=True requests parallel evaluation across list elements, but it should be used only when each element computation supplies enough work to amortize threading overhead.

Follow-up: Why can this be counterproductive in group-by code? Group execution is already parallelized, so adding inner parallelism can create unnecessary nested parallel work.

QHow does list.eval differ from arr.eval and list.agg?

The method is for the List datatype, whose lists can vary in length. For fixed-size Array values, use the corresponding arr.eval method instead.

Follow-up: What related method preserves list results while agg may unwrap them? list.eval always returns a list, whereas list.agg can automatically explode a statically single-valued result.

polars.Expr.list.agg
polars.Expr.arr.eval
polars.element
polars.Expr.list

Source: polars.Expr.list.eval. Checked 2026-10-15.