Skip to main content
`Ctrl`+`K`

# pandas.DataFrame.stack

DataFrame.stack(level=-1, dropna=<no_default>, sort=<no_default>, future_stack=True)

  Stack the prescribed level(s) from columns to index.

  Return a reshaped DataFrame or Series having a multi-level index with one or more new inner-most levels compared to the current DataFrame. The new inner-most levels are created by pivoting the columns of the current dataframe:

  - if the columns have a single level, the output is a Series;

  - if the columns have multiple levels, the new index level(s) is (are) taken from the prescribed level(s) and the output is a DataFrame.

  Parameters:
    level int, str, list, default -1

      Level(s) to stack from the column axis onto the index axis, defined as one index or label, or a list of indices or labels.

    dropna bool, default True

      Whether to drop rows in the resulting Frame/Series with missing values. Stacking a column level onto the index axis can create combinations of index and column values that are missing from the original dataframe. See Examples section.

      Deprecated since version 3.0: This parameter is deprecated and will be removed in a future version of pandas.

    sort bool, default True

      Whether to sort the levels of the resulting MultiIndex.

      Deprecated since version 3.0: This parameter is deprecated and will be removed in a future version of pandas.

    future_stack bool, default True

      Whether to use the new stack implementation. This is the default as of pandas 3.0. When True, dropna and sort have no impact on the result and must remain unspecified. See pandas 2.1.0 Release notes for more details.

      Deprecated since version 3.0: This parameter is deprecated and will be removed in a future version of pandas.

  Returns:
    DataFrame or Series

      Stacked dataframe or series.

  See also

  `DataFrame.unstack`

    Unstack prescribed level(s) from index axis onto column axis.

  `DataFrame.pivot`

    Reshape dataframe from long format to wide format.

  `DataFrame.pivot_table`

    Create a spreadsheet-style pivot table as a DataFrame.

  Notes

  The function is named by analogy with a collection of books being reorganized from being side-by-side horizontally (the columns of the DataFrame) to being stacked vertically on top of each other (in the index of the DataFrame).

  Reference the user guide for more examples.

  Examples

  Single level columns

      >>> df_single_level_cols = pd.DataFrame(
      ...     [[0, 1], [2, 3]], index=["cat", "dog"], columns=["weight", "height"]
      ... )

  Stacking a dataframe with a single level column axis returns a Series:

      >>> df_single_level_cols
           weight height
      cat       0      1
      dog       2      3
      >>> df_single_level_cols.stack()
      cat  weight    0
           height    1
      dog  weight    2
           height    3
      dtype: int64

  Multi level columns: simple case

      >>> multicol1 = pd.MultiIndex.from_tuples(
      ...     [("weight", "kg"), ("weight", "pounds")]
      ... )
      >>> df_multi_level_cols1 = pd.DataFrame(
      ...     [[1, 2], [2, 4]], index=["cat", "dog"], columns=multicol1
      ... )

  Stacking a dataframe with a multi-level column axis:

      >>> df_multi_level_cols1
           weight
               kg    pounds
      cat       1        2
      dog       2        4
      >>> df_multi_level_cols1.stack()
                  weight
      cat kg           1
          pounds       2
      dog kg           2
          pounds       4

  Missing values

      >>> multicol2 = pd.MultiIndex.from_tuples([("weight", "kg"), ("height", "m")])
      >>> df_multi_level_cols2 = pd.DataFrame(
      ...     [[1.0, 2.0], [3.0, 4.0]], index=["cat", "dog"], columns=multicol2
      ... )

  It is common to have missing values when stacking a dataframe with multi-level columns, as the stacked dataframe typically has more values than the original dataframe. Missing values are filled with NaNs:

      >>> df_multi_level_cols2
          weight height
              kg      m
      cat    1.0    2.0
      dog    3.0    4.0
      >>> df_multi_level_cols2.stack()
              weight  height
      cat kg     1.0     NaN
          m      NaN     2.0
      dog kg     3.0     NaN
          m      NaN     4.0

  Prescribing the level(s) to be stacked

  The first parameter controls which level or levels are stacked:

      >>> df_multi_level_cols2.stack(0)
                   kg    m
      cat weight  1.0  NaN
          height  NaN  2.0
      dog weight  3.0  NaN
          height  NaN  4.0
      >>> df_multi_level_cols2.stack([0, 1])
      cat  weight  kg    1.0
           height  m     2.0
      dog  weight  kg    3.0
           height  m     4.0
      dtype: float64