Convert wide tables to tidy long data
Normalize tables where separate measurement columns represent categories such as months, metrics, or statuses.
Pandas · Function
pd.melt
pandas.melt reshapes a DataFrame from wide to long format. It preserves selected identifier columns and unpivots measured columns into variable and value columns.
How it works
pandas.melt reshapes a DataFrame from wide to long form. Columns listed in id_vars remain as identifiers; selected measured columns become a variable column and a value column, with optional control over their names, MultiIndex column level, and index retention.
Syntax
pandas.melt(frame, id_vars=None, value_vars=None, var_name=None, value_name='value', col_level=None, ignore_index=True)Parameters
| Name | Type | Description |
|---|---|---|
frame | DataFrame | DataFrame to reshape from wide to long form. |
id_vars | scalar, tuple, list, or ndarray, optional | Columns to keep as identifier variables. |
value_vars | scalar, tuple, list, or ndarray, optional | Columns to unpivot; when omitted, all columns not in id_vars are used. |
var_name | scalar, optional | Name for the output variable column; defaults from frame.columns.name or variable. |
value_name | scalar, optional | Name for the output value column; defaults to value and cannot already be a column label. |
col_level | scalar, optional | MultiIndex column level to melt. |
ignore_index | bool, optional | Whether to ignore the original index; defaults to True. |
Returns
DataFrame
Key points
- Use melt to convert column-oriented measurements into row-oriented records while retaining selected identifiers.
- Omitting value_vars automatically unpivots every non-identifier column.
- var_name sets the output column containing the original measured-column labels.
- With var_name=None, pandas derives the variable-column name from the frame’s column name or uses variable.
- value_name controls the measured-values column and must be unique among existing labels.
- col_level lets melt operate on a selected level of MultiIndex columns.
- The default ignore_index=True creates a fresh sequential index for the reshaped result.
Common mistakes
- value_name must not match an existing column label.
- Setting ignore_index=False preserves the source index and repeats labels for the generated rows.
Example: Convert wide data to long format
import pandas as pd
wide = pd.DataFrame({
"city": ["Paris", "Berlin"],
"jan": [10, 12],
"feb": [11, 13],
})
long = pd.melt(
wide,
id_vars=["city"],
value_vars=["jan", "feb"],
var_name="month",
value_name="temperature",
)
print(long)This converts the month columns into rows while retaining city as the identifier.
When to use it
Support downstream analysis
Prepare data for grouped analysis or visualization libraries that expect one observation per row.
Melt a MultiIndex column level
Reshape tables with hierarchical column labels by selecting the relevant MultiIndex level.
Interview questions
QWhat does pandas.melt do?
It reshapes wide data into long data. Identifier columns stay in place, while measured columns are converted into rows represented by variable and value columns.
Follow-up: How are measured columns chosen when value_vars is omitted? All columns not listed in id_vars are used.
QHow do id_vars and value_vars affect the result?
id_vars identifies columns to keep unchanged as identifiers. value_vars selects the columns to unpivot; if omitted, every column not in id_vars is unpivoted.
Follow-up: How would you keep several identifying fields? Pass them together as a list or tuple to id_vars.
QWhich options control output names and index behavior?
By default, melt creates variable and value columns and discards the original index. var_name and value_name customize those columns, while ignore_index=False retains the original index.
Follow-up: What if the input has MultiIndex columns? Use col_level to choose the level to melt.
Related
DataFrame.meltDataFrame.pivotDataFrame.pivot_tablepandas.wide_to_long