Pandas · Function

pd.wide_to_long

Unpivot a DataFrame whose measured columns share stub prefixes and suffixes. Identifier columns become part of the resulting index, while the extracted suffix is named by j.

How it works

Provide the wide DataFrame, stub names for column groups, identifier columns, and the name for the extracted suffix. Matching columns such as A_2023 and A_2024 are reshaped into an A column indexed by the identifiers and the suffix; other columns remain unchanged.

Syntax

pandas.wide_to_long(df, stubnames, i, j, sep='', suffix='\d+')

Parameters

Name	Type	Description
`df`	`DataFrame`	The wide-format DataFrame.
`stubnames`	`str or list-like`	The stub name or names; wide variables are assumed to start with them.
`i`	`str or list-like`	Column or columns used as identifier variables.
`j`	`str`	Name of the sub-observation variable in the long format.
`sep`	`str, default ''`	Separator in wide column names to strip from long-format names; default is an empty string.
`suffix`	`str, default '\d+'`	Regular expression capturing the desired suffixes; default is '\d+'.

Returns

DataFrame containing each stub name as a variable, with a new index formed from (i, j).

Key points

Use the function to turn repeated suffix-based columns into rows in a long-format DataFrame.
It is a convenient alternative to melt when the column groups follow a predictable stub-and-suffix layout.
Each stub name acts as the prefix used to discover its corresponding wide-format columns.
The i argument identifies columns that distinguish the original observations and become index levels.
The j argument names the index level holding each extracted suffix.
Columns not matched as stub-and-suffix measurements are retained in the result.

Common mistakes

The default suffix pattern is numeric; use a regular expression such as \D+ when suffixes contain no numbers.
Numeric suffixes are converted to numeric index values, so the j level may not remain text.

Example: Convert year-suffixed columns to long format

import pandas as pd

df = pd.DataFrame({
    "id": [1, 2],
    "A_2023": [10, 20],
    "A_2024": [11, 21],
})

long = pd.wide_to_long(df, stubnames="A", i="id", j="year", sep="_")
print(long.reset_index())

The identifier column remains an index level, while matching A_year columns become one A value column and a year sub-observation column.

When to use it

Normalize time-suffixed measurements

Transform columns such as sales_2023 and sales_2024 into one sales column indexed by year.

Unpivot multiple stub groups

Reshape several parallel groups such as A_2023 and B_2023 together.

Prepare tidy analytical data

Preserve identifiers and unrelated metadata while converting repeated measurements to rows.

Interview questions

QWhat does pandas.wide_to_long do?

It reshapes columns grouped by a shared stub and suffix into a long DataFrame. The supplied i columns identify rows, while j names the extracted suffix level.

Follow-up: How would you handle columns such as A-2023? Pass sep="-" so the separator is removed when forming the long-format names.

QHow do stubnames, i, and j control the reshape?

stubnames identifies the prefixes of measured-column groups, i supplies identifier columns, and j names the sub-observation variable. For example, stubnames="A" matches A1 and A2 with the default separator and suffix rules.

Follow-up: How can multiple measured groups be reshaped together? Supply a list-like stubnames value, such as ["A", "B"].

QWhen should sep or suffix be changed?

sep specifies the separator between a stub and suffix and is stripped from long-format names. suffix is a regular expression for accepted suffixes; the default \d+ selects numeric suffixes.

Follow-up: What pattern selects nonnumeric suffixes? Use a negated digit class such as \D+ when the suffixes contain no numbers.

pandas.melt
DataFrame.melt
pandas.pivot

Source: pandas.wide_to_long. Checked 2026-10-15.