Polars · Module

.cum_sum

Returns an expression that computes a running sum for the named column values. It is shorthand for applying Expr.cum_sum to a column expression.

How it works

pl.cum_sum selects a column and returns an expression whose value at each row is the running total through that row. It is shorthand for selecting the column expression and calling its cum_sum method; use cum_sum_horizontal for row-wise accumulation across columns.

Syntax

polars.cum_sum(names: str) -> Expr

Parameters

Name	Type	Description
`names`	`str`	Name(s) of the columns to use in the aggregation.

Returns

Expr

Key points

Computes a running total for the selected column values.
Equivalent to calling cum_sum on the corresponding column expression.
The names argument specifies which column or columns supply the values.
Use the horizontal cumulative-sum operation when accumulation should span columns within each row.
The documented single-column example returns one output column with three rows.

Common mistakes

This module-level function is a convenience wrapper around the column expression method; it does not perform a horizontal accumulation.

Example: Cumulative column total

import polars as pl

df = pl.DataFrame({"a": [1, 2, 3]})
result = df.select(pl.cum_sum("a"))
print(result)

Creates a cumulative total for column a, producing 1, 3, and 6.

When to use it

Cumulative metrics

Select a running total from a DataFrame or LazyFrame query.

Concise expression construction

Build expression pipelines without manually constructing pl.col(name).cum_sum().

Aggregation direction

Choose between vertical and row-wise cumulative aggregation.

Interview questions

QWhat does polars.cum_sum return, and what is it shorthand for?

It returns an expression containing the cumulative sum of the named column. The function is syntactic sugar for col(names).cum_sum().

Follow-up: How would you calculate cumulative totals across several columns in each row? Use cum_sum_horizontal rather than this vertical column operation.

QWhat is the purpose of the names parameter?

The names parameter identifies the column or columns used in the aggregation. The returned expression can be passed to DataFrame.select or another expression context.

Follow-up: What happens when the expression is used in a lazy query? It remains part of the query plan until collection, allowing Polars to optimize the surrounding computation.

QWhat result does a cumulative sum produce?

For a column containing 1, 2, and 3, selecting pl.cum_sum("a") yields 1, 3, and 6. Each output row includes the current value plus all preceding values.

Follow-up: Which related function should be chosen for horizontal accumulation? Choose cum_sum_horizontal when values from multiple columns must be accumulated across each row.

polars.Expr.cum_sum
polars.cum_sum_horizontal
polars.col

Source: polars.cum_sum — Polars documentation. Checked 2026-10-15.