Pandas · Function

pd.pivot_table

Create a spreadsheet-style pivot table from a DataFrame by grouping row and column keys and aggregating selected values. The result is a DataFrame whose axes may be hierarchical.

How it works

The method groups selected values by keys for the result index and columns, applies an aggregation function, and returns a DataFrame. The resulting axes can be hierarchical MultiIndex objects; optional margins add partial aggregates.

Syntax

DataFrame.pivot_table(*values=None*, *index=None*, *columns=None*, *aggfunc='mean'*, *fill_value=None*, *margins=False*, *dropna=True*, *margins_name='All'*, *observed=True*, *sort=True*, ***kwargs*)

Parameters

Name	Type	Description
`values`	`list-like or scalar, optional`	Column or columns to aggregate.
`index`	`column, Grouper, array, or sequence of the previous`	Keys to group by on the pivot table index; may be a column, Grouper, array, or sequence.
`columns`	`column, Grouper, array, or sequence of the previous`	Keys to group by on the pivot table column; may be a column, Grouper, array, or sequence.
`aggfunc`	`function, list of functions, dict, default "mean"`	Aggregation function, list of functions, or dictionary; defaults to mean.
`fill_value`	`scalar, default None`	Value used to replace missing values in the resulting pivot table.
`margins`	`bool, default False`	Whether to add partial aggregates.
`dropna`	`bool, default True`	Whether to omit rows or columns whose entries are all NaN.
`margins_name`	`str, default "All"`	Name used for the margins label.
`observed`	`bool, default True`	Whether to include unobserved categorical combinations.
`sort`	`bool, default True`	Whether to sort the result levels.
`**kwargs`	`dict`	Additional keyword arguments accepted by the aggregation operation.

Returns

DataFrame — An Excel style pivot table.

Key points

The method returns a DataFrame arranged like a spreadsheet pivot table.
Grouped levels are represented by MultiIndex objects on the result's index and columns.
index supplies the keys used to form row groups.
columns supplies the keys used to form column groups.
A dictionary aggfunc lets different value columns use different aggregation functions.

Common mistakes

fill_value is applied after aggregation, so it fills missing cells in the resulting table rather than changing input data.
Passing multiple aggregation functions creates hierarchical columns, which can change how result columns must be selected.
A list of grouping keys may combine supported key types, but nested lists are not valid as individual keys.

Example: Summarize grouped sales

import pandas as pd

df = pd.DataFrame({
    "region": ["East", "East", "West"],
    "product": ["A", "B", "A"],
    "sales": [10, 20, 15],
})

result = df.pivot_table(
    values="sales",
    index="region",
    columns="product",
    aggfunc="sum",
    fill_value=0,
)
print(result)

Groups sales by region and product, sums each group, and replaces missing combinations with zero.

When to use it

Cross-tabulated summaries

Summarize numeric measures across two or more categorical dimensions.

Report totals

Add row and column totals to a grouped report.

Per-column aggregation

Apply different aggregations to different value columns.

Interview questions

QWhat does DataFrame.pivot_table do?

It creates an Excel-style pivot table by grouping values on index and column keys and aggregating them. The result is a DataFrame, and its index or columns may be MultiIndex objects.

Follow-up: How would you produce totals? Set margins=True; the aggregation function is also used to calculate the partial aggregates.

QHow do values, index, and columns affect the result?

values selects the column or columns to aggregate. index and columns define the grouping keys for the result's row and column axes, respectively.

Follow-up: Can grouping keys be arrays? Yes, an array can be used, but it must have the same length as the input data.

QWhat forms can aggfunc take?

aggfunc defaults to mean and can be a function, a list of functions, or a dictionary. A dictionary maps each aggregated column to a function or list of functions.

Follow-up: What structural effect does a function list have? The resulting columns become hierarchical, with function names inferred from the function objects.

pandas.DataFrame.pivot
pandas.pivot_table
pandas.crosstab
pandas.DataFrame.groupby

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