Polars · Function

agg

Compute one or more aggregations for every group in a DataFrame group-by operation. Positional expressions and named keyword aggregations can be combined.

How it works

GroupBy.agg computes one or more expressions independently for every group created by group_by. Positional expressions determine aggregation columns from their expressions, while keyword expressions additionally rename their results to the supplied keyword; string positional inputs are interpreted as column names.

Syntax

GroupBy.agg(*aggs: IntoExpr | Iterable[IntoExpr], **named_aggs: IntoExpr) → DataFrame

Parameters

Name	Type	Description
`aggs`	`IntoExpr \| Iterable[IntoExpr]`	Aggregations to compute for each group of the group by operation, specified as positional arguments. Accepts expression input; strings are parsed as column names.
`named_aggs`	`IntoExpr`	Additional aggregations, specified as keyword arguments. The resulting columns will be renamed to the keyword used.

Returns

DataFrame

Key points

The method evaluates aggregation expressions separately within each group and returns the grouped result.
Use positional arguments for the main collection of aggregations passed to aggs.
Aggregation arguments can be Polars expressions, such as pl.col("value").sum().
Keyword arguments add further aggregation expressions alongside positional ones.
A keyword aggregation uses its keyword as the output column name.

Common mistakes

Passing a string as a positional aggregation refers to that column rather than treating the string as a literal value.

Example: Aggregate grouped scores

import polars as pl

df = pl.DataFrame({"team": ["A", "A", "B"], "score": [3, 5, 4]})
result = df.group_by("team").agg(
    pl.col("score").sum().alias("total_score"),
    average=pl.col("score").mean(),
)
print(result)

Groups rows by team and computes both a positional sum expression and a named mean expression.

When to use it

Grouped summaries

Summarize numeric measures such as totals, averages, or counts separately for each category.

Named output metrics

Produce several result columns while assigning stable, readable names through keyword aggregations.

Interview questions

QWhat does GroupBy.agg do?

GroupBy.agg computes aggregations for every group produced by a group-by operation. It accepts expressions as positional arguments, and keyword arguments provide additional aggregations whose output names come from the keywords.

Follow-up: How can an aggregation column be named explicitly? Use a keyword aggregation, such as total=pl.col("amount").sum(), or alias the expression.

QWhat can the aggs parameter contain?

Positional aggregations are supplied through the aggs parameter, which accepts an expression or an iterable of expressions. Strings in that position are interpreted as column names.

Follow-up: What happens when several expressions are provided? Each expression contributes an aggregation result for every group.

QHow are named aggregations represented in the result?

Keyword aggregations are supplied through named_aggs. The resulting columns are renamed to the corresponding keyword, which makes the output schema explicit.

Follow-up: Why use a keyword aggregation instead of only an alias? It directly associates the desired output name with the expression at the call site.

polars.DataFrame.group_by
polars.lazyframe.group_by.LazyGroupBy.agg

Source: polars.dataframe.group_by.GroupBy.agg — Polars documentation. Checked 2026-10-15.

agg