Skip to main content
`Ctrl`+`K`

# pandas.MultiIndex.set_levels

MultiIndex.set_levels(levels, *, level=None, verify_integrity=True)

  Set new levels on MultiIndex. Defaults to returning new index.

  The set_levels method provides a flexible way to change the levels of a MultiIndex. This is particularly useful when you need to update the index structure of your DataFrame without altering the data. The method returns a new MultiIndex unless the operation is performed in-place, ensuring that the original index remains unchanged unless explicitly modified.

  The method checks the integrity of the new levels against the existing codes by default, but this can be disabled if you are confident that your levels are consistent with the underlying data. This can be useful when you want to perform optimizations or make specific adjustments to the index levels that do not strictly adhere to the original structure.

  Parameters:
    levels sequence or list of sequence

      New level(s) to apply.

    level int, level name, or sequence of int/level names (default None)

      Level(s) to set (None for all levels).

    verify_integrity bool, default True

      If True, checks that levels and codes are compatible.

  Returns:
    MultiIndex

      A new MultiIndex with the updated levels.

  See also

  `MultiIndex.set_codes`

    Set new codes on the existing MultiIndex.

  `MultiIndex.remove_unused_levels`

    Create new MultiIndex from current that removes unused levels.

  `Index.set_names`

    Set Index or MultiIndex name.

  Examples

      >>> idx = pd.MultiIndex.from_tuples(
      ...     [
      ...         (1, "one"),
      ...         (1, "two"),
      ...         (2, "one"),
      ...         (2, "two"),
      ...         (3, "one"),
      ...         (3, "two"),
      ...     ],
      ...     names=["foo", "bar"],
      ... )
      >>> idx
      MultiIndex([(1, 'one'),
          (1, 'two'),
          (2, 'one'),
          (2, 'two'),
          (3, 'one'),
          (3, 'two')],
         names=['foo', 'bar'])

      >>> idx.set_levels([["a", "b", "c"], [1, 2]])
      MultiIndex([('a', 1),
                  ('a', 2),
                  ('b', 1),
                  ('b', 2),
                  ('c', 1),
                  ('c', 2)],
                 names=['foo', 'bar'])
      >>> idx.set_levels(["a", "b", "c"], level=0)
      MultiIndex([('a', 'one'),
                  ('a', 'two'),
                  ('b', 'one'),
                  ('b', 'two'),
                  ('c', 'one'),
                  ('c', 'two')],
                 names=['foo', 'bar'])
      >>> idx.set_levels(["a", "b"], level="bar")
      MultiIndex([(1, 'a'),
                  (1, 'b'),
                  (2, 'a'),
                  (2, 'b'),
                  (3, 'a'),
                  (3, 'b')],
                 names=['foo', 'bar'])

  If any of the levels passed to `set_levels()` exceeds the existing length, all of the values from that argument will be stored in the MultiIndex levels, though the values will be truncated in the MultiIndex output.

      >>> idx.set_levels([["a", "b", "c"], [1, 2, 3, 4]], level=[0, 1])
      MultiIndex([('a', 1),
          ('a', 2),
          ('b', 1),
          ('b', 2),
          ('c', 1),
          ('c', 2)],
         names=['foo', 'bar'])
      >>> idx.set_levels([["a", "b", "c"], [1, 2, 3, 4]], level=[0, 1]).levels
      FrozenList([['a', 'b', 'c'], [1, 2, 3, 4]])