Long-form reshaping
Convert wide, single-level columns into a labeled long-form Series for iteration or downstream grouping.
Pandas · Module
df.stack
Reshapes a DataFrame by moving selected column levels into the index. The result is a Series for single-level columns or a DataFrame when remaining column levels exist.
How it works
DataFrame.stack reshapes columns into one or more innermost index levels. With ordinary single-level columns it returns a Series; with selected levels from MultiIndex columns it can return a DataFrame. Missing-value removal and level ordering are controlled by the optional arguments.
Syntax
DataFrame.stack(*level=-1*, *dropna=<no_default>*, *sort=<no_default>*, *future_stack=True*)Parameters
| Name | Type | Description |
|---|---|---|
level | int, str, or list; default -1 | Column level or levels to move to the index; an integer, label, or list of integers or labels. Default: -1. |
dropna | bool; default True | Whether to remove rows containing missing values from the result. Default: True. |
sort | bool; default True | Whether to sort the resulting MultiIndex levels. Default: True. |
future_stack | bool; default True | Whether to use the newer stacking implementation intended to replace the current one in pandas 3.0. Default: True in the current stable documentation. |
Returns
DataFrame or Series — the stacked dataframe or series.
Key points
- The operation pivots selected column levels into the row index.
- The output is reshaped and gains an additional inner index level.
- Single-level columns produce a Series after stacking.
- For MultiIndex columns, the selected column levels become new index levels.
- level accepts an integer, label, or list to choose which columns levels move.
- dropna determines whether missing-valued rows are excluded from the output.
- sort determines whether the generated MultiIndex levels are ordered.
Common mistakes
- The default behavior removes result rows whose values are missing; choose dropna=False when those rows must remain.
- The result's MultiIndex levels may be sorted by default; set sort explicitly when preserving or controlling ordering matters.
- future_stack selects the newer implementation, and its default differs between the current stable documentation and older releases.
Example: Stack columns into the index
import pandas as pd
df = pd.DataFrame(
{"name": ["Alice", "Bob"], "score": [90, 85]},
index=["exam1", "exam2"],
)
print(df.stack())This converts the single-level columns into an inner index level, producing a Series with row labels and column names in its MultiIndex.
When to use it
MultiIndex column transformation
Move selected levels of hierarchical columns into the row index while retaining other column levels.
Missing-data control
Preserve or remove missing-valued combinations during reshaping according to downstream data requirements.
Interview questions
QWhat does DataFrame.stack do?
stack moves the selected column level or levels onto the index and creates new innermost MultiIndex levels. If the columns have one level, the result is a Series; with multiple column levels, the result can be a DataFrame.
Follow-up: What happens when columns are a MultiIndex and only one level is stacked? The chosen level becomes an innermost index level, while the unstacked column levels remain columns, so the result stays a DataFrame.
QHow is the level argument used?
level identifies the column level or levels to move, using an integer position, a label, or a list of either. Its default is -1, which selects the last column level.
Follow-up: How would you stack two named levels? Pass their labels as a list, for example level=["region", "metric"], provided those levels exist in the column index.
QWhat do dropna, sort, and future_stack control?
dropna controls whether rows containing missing values are removed from the reshaped result, while sort controls ordering of the resulting MultiIndex levels. Both options are configurable rather than requiring a separate cleanup step.
Follow-up: When should future_stack be considered? Use it to opt into the newer implementation that is intended to replace the current one in pandas 3.0, while checking compatibility with the surrounding code.
Related
DataFrame.unstackDataFrame.meltDataFrame.pivotDataFrame.droplevel