Pandas · Function

df.groupby

Groups a DataFrame by labels, mappings, functions, pd.Grouper objects, or index levels. It returns a groupby object for later aggregation, transformation, or other group-wise operations.

How it works

Calling groupby partitions a DataFrame according to one or more grouping specifications and returns a groupby object. You can then apply reductions or transformations such as sum, mean, or apply; grouping can use columns, mappings, functions, labels, or a Grouper.

Syntax

DataFrame.groupby(by=None, level=None, *, as_index=True, sort=True, group_keys=True, observed=True, dropna=True)

Parameters

Name	Type	Description
`by`	`mapping, function, label, pd.Grouper, or list`	Mapping, function, label, pd.Grouper, or list of such; determines the groups.
`level`	`int, level name, or sequence`	Index level or levels used for grouping when the axis is a MultiIndex.
`as_index`	`bool`	Whether group labels are returned as the index; default is True.
`sort`	`bool`	Whether to sort group keys; default is True.
`group_keys`	`bool`	Whether grouping keys are included when applying functions; default is True.
`observed`	`bool`	Whether unobserved categorical groups are included; default is True in the current stable documentation.
`dropna`	`bool`	Whether NA group keys are excluded; default is True.

Returns

DataFrameGroupBy: a groupby object containing information about the groups.

Key points

Use groupby to organize DataFrame rows according to a mapper or column-based Series before applying group operations.
The operation follows the split–apply–combine pattern: form groups, perform a group-wise operation, and assemble the result.
The by value identifies how rows are assigned to groups and may be a label, mapping, function, pd.Grouper, or list.
In versions where axis is available, it selects row-wise or column-wise grouping; row-wise grouping is the default.
as_index affects DataFrame results by deciding whether group labels are placed in the index.

Common mistakes

by and level are alternative ways to define groups; passing both is invalid.
With the default as_index=True, group labels become the result index; use as_index=False when ordinary columns are preferred.
Use level to group an axis level when the DataFrame has a MultiIndex.

Example: Aggregate rows by a column

import pandas as pd

df = pd.DataFrame({
    "team": ["A", "A", "B"],
    "points": [10, 15, 7],
})

result = df.groupby("team", as_index=False)["points"].sum()
print(result)

Groups rows by team and returns the sum of points for each team as ordinary columns.

When to use it

Grouped aggregation

Summarize numeric measurements per category, such as total sales by region.

Group-wise processing

Apply custom logic independently to each subset of rows.

MultiIndex grouping

Work with hierarchical indexes by selecting one or more index levels.

Interview questions

QWhat does DataFrame.groupby return and when does aggregation occur?

groupby returns a groupby object rather than immediately computing an aggregate. The grouping operation separates data into groups, after which methods such as sum, mean, or apply can combine results.

Follow-up: How would you preserve group labels as columns? Pass as_index=False, which prevents labels from becoming the result index.

QWhat can be supplied to the by parameter?

The by argument accepts a mapping, function, label, pd.Grouper, or a list of these. A function is applied to each value of the object’s index to determine its group.

Follow-up: How can hierarchical index groups be selected instead? Use level with the relevant index level, without also supplying by.

QWhich options commonly affect the groups that appear in the result?

sort=True controls whether group keys are sorted, while dropna=True controls whether NA group keys are omitted. observed=True controls categorical grouping so only observed category combinations are used.

Follow-up: What should be checked when categorical groups or missing keys appear unexpectedly? Review observed and dropna, because both change which groups are represented.

pandas.DataFrameGroupBy
pandas.Grouper
DataFrameGroupBy.apply
DataFrameGroupBy.agg
DataFrameGroupBy.get_group

Source: pandas.DataFrame.groupby — pandas 3.0.6 documentation. Checked 2026-10-15.