Skip to main content
v2026.11,986 entries · CC-BY 4.0

MultiIndex in pandas: Create, Select, Sort and Reset

How to create, select from, sort and reset a pandas MultiIndex, with the documented errors and a worked research-data example.

Written and maintained by CASRAI Editorial Board

Published

On this page

A pandas MultiIndex is a hierarchical index: an index object that holds several levels, so each row (or column) label is a tuple such as (site, year) and each tuple is unique. You build one with pd.MultiIndex.from_arrays, from_tuples, from_product or from_frame, select from it with .loc, xs and pd.IndexSlice, and turn its levels back into ordinary columns with reset_index. The pandas MultiIndex (also searched as “multiindex pandas”) is what lets one two-dimensional DataFrame carry data that is really grouped by site, cohort, wave or instrument.

This guide follows the pandas 3.1.1 documentation: how to create a MultiIndex, how to select from it without surprises, why it must be sorted, how to flatten it, and which documented errors to expect. The worked example is constructed in code and is illustrative, not real data.

What a MultiIndex is used for in research

Research data is rarely a single flat table. Measurements are nested: repeated observations within participants, participants within sites, sites within waves. A MultiIndex stores that nesting in the index itself. The pandas API reference describes the class as a “multi-level, or hierarchical, index object” and as an array of tuples where each tuple is unique (pandas.MultiIndex reference, read 2026-11-14).

Typical research uses include panel-style layouts (entity by time period), results of a groupby on more than one key, and the output of pivot_table and stack/unstack, which can return MultiIndex objects. If you are working with entity-by-time data in an econometric setting, the panel data analysis guide covers the models; this page covers the pandas container.

When a MultiIndex helps and when it does not

A MultiIndex is useful when you will repeatedly select by one or more levels, aggregate by a level, or reshape between wide and long layouts. If you only ever filter on column values, ordinary columns and boolean masks are simpler, and DataFrame.query() reads well for that. A MultiIndex is not required to store grouped data; it is a convenience for label-based access to it.

Access: MultiIndex is part of pandas

There is no separate package for the pandas MultiIndex. It is the class pandas.MultiIndex, reached as pd.MultiIndex after import pandas as pd. Its constructor signature in the pandas 3.1.1 API reference is MultiIndex(levels=None, codes=None, sortorder=None, names=None, copy=False, name=None, verify_integrity=True). In day-to-day work you almost never call it directly; you use the four from_* constructors below, or pass a list of arrays to a Series or DataFrame and let pandas build the index.

The reference lists these attributes: names, levels, codes, nlevels, levshape and dtypes. It lists these methods among others: to_frame, to_flat_index, droplevel, swaplevel, reorder_levels, sortlevel, get_loc, get_locs, get_loc_level, remove_unused_levels, set_levels, set_codes and drop.

Step by step: create, select, sort and reset a MultiIndex

Step 1. Create the MultiIndex

Choose the constructor that matches the shape of the data you already hold. The data table below compares the four documented constructors, the input each takes and the size of the example in the pandas documentation.

  1. MultiIndex.from_arrays takes a list of arrays, one array per level. The API reference example is arrays = [[1, 1, 2, 2], ["red", "blue", "red", "blue"]] followed by pd.MultiIndex.from_arrays(arrays, names=("number", "color")), which returns MultiIndex([(1, 'red'), (1, 'blue'), (2, 'red'), (2, 'blue')], names=['number', 'color']).
  2. MultiIndex.from_tuples takes a list of tuples. The user guide builds it with tuples = list(zip(*arrays)) and then pd.MultiIndex.from_tuples(tuples, names=["first", "second"]).
  3. MultiIndex.from_product takes a list of iterables and builds every combination. The user guide example is iterables = [["bar", "baz", "foo", "qux"], ["one", "two"]] and pd.MultiIndex.from_product(iterables, names=["first", "second"]), which yields the same eight tuples as the from_tuples example.
  4. MultiIndex.from_frame takes a DataFrame and uses its columns as levels. It is described as the complement of to_frame.

If you do not pass names, the levels are given the name None. Name them: named levels make xs, sort_index(level=...) and reset_index readable. Names cannot be set by assigning through .levels; use MultiIndex.set_names instead. For a DataFrame, rename_axis(index=["site", "year"]) names the index levels, which the documentation notes is useful before reset_index.

A shortcut the user guide documents: pass a list of arrays directly as the index of a Series or DataFrame and pandas constructs the MultiIndex automatically.

Step 2. Select with loc, xs and IndexSlice

With a DataFrame df whose index has levels named first and second, the documented selection tools are:

  • df.loc["bar"] selects the outer level label. Selecting a column by the outer column level works with plain brackets (df["bar"]), but on a transposed frame df.T["bar"] raises KeyError; use df.T.loc["bar"].
  • df.xs("one", level="second") takes a cross-section at one value of a named level, whatever its position. By default the selected level is dropped from the result; drop_level=False keeps it.
  • df.xs(("one", "bar"), level=("second", "first"), axis=1) selects on several levels at once; the user guide shows this on columns with axis=1.
  • pd.IndexSlice gives “a more natural syntax using :, rather than using slice(None)“. The documented form is idx = pd.IndexSlice then dfmi.loc[idx[:, :, ["C1", "C3"]], idx[:, "foo"]].

Label slices on a MultiIndex include both endpoints. Always give both axes to .loc: the documentation says to specify the indexer for the index and for the columns, so write df.loc[(slice("A1", "A3"), ...), :] with the trailing , : rather than leaving the column axis out.

List of tuples versus tuple of lists

This is the distinction most tutorials skip, and it changes the result. A list of tuples is a set of complete keys: s.loc[[("A", "c"), ("B", "d")]] returns exactly the rows (A, c) and (B, d). A tuple of lists is a product of level values: s.loc[(["A", "B"], ["c", "d"])] returns every combination of A or B with c or d, so up to four rows. If you expected two rows and got four, you passed a tuple of lists.

Step 3. Sort the index before slicing

The user guide says a MultiIndex needs to be sorted for effective indexing. Unsorted indexing still works for simple cases, but it is inefficient, raises a PerformanceWarning and returns a copy of the data rather than a view. Range slices can fail outright: the documentation shows dfm.loc[(0, 'y'):(1, 'z')] raising UnsortedIndexError: 'Key length (2) was greater than MultiIndex lexsort depth (1)'. The fix it shows is dfm = dfm.sort_index(), after which dfm.index.is_monotonic_increasing is True and the same slice returns the expected rows.

sort_index() sorts by all levels; sort_index(level=0), sort_index(level=1) or sort_index(level="second") sorts by a single level. Make df = df.sort_index() the line immediately after you build or load an indexed frame, and check df.index.is_monotonic_increasing when a slice misbehaves.

Step 4. Reorder, reset and flatten

  • df.swaplevel(0, 1, axis=0) exchanges two levels. df.reorder_levels([1, 0], axis=0) “generalizes the swaplevel method, allowing you to permute the hierarchical index levels in one step”; for two levels the two calls give the same result.
  • df.reset_index() turns every index level into a column. The signature in the pandas 3.1.1 reference is DataFrame.reset_index(level=None, *, drop=False, inplace=no_default, col_level=0, col_fill='', allow_duplicates=False, names=None). Pass level="class" to move only that level and keep the rest as the index; each removed level becomes a column. For a MultiIndex, names must be a list with one entry per level. drop=True discards the levels instead.
  • The inplace argument of reset_index is deprecated as of pandas 3.1.0 and the reference states it is removed in 4.0, so assign the result (df = df.reset_index()) in new code.
  • MultiIndex.to_flat_index() returns the index as a flat Index of tuples, and droplevel removes a level entirely. These two methods are listed in the API reference; check their pages for arguments before relying on them in a pipeline.

Worked example: site by year by measure

The following example is an illustrative construction with invented values, written to show the mechanics. It does not represent any real study or site.

import pandas as pd

index = pd.MultiIndex.from_product(
    [["A", "B"], [2022, 2023]],
    names=["site", "year"],
)
df = pd.DataFrame(
    {"ph": [7.1, 7.3, 6.8, 6.9],
     "conductivity": [410, 425, 380, 395]},
    index=index,
).sort_index()

df.index.is_monotonic_increasing   # True
df.loc["A"]                        # both years for site A
df.xs(2023, level="year")          # one row per site for 2023
df.loc[("B", 2022), "ph"]          # a single value
flat = df.reset_index()            # columns: site, year, ph, conductivity

The frame has four rows: (A, 2022), (A, 2023), (B, 2022), (B, 2023). from_product is the right constructor because the design is fully crossed, every site observed in every year. df.loc["A"] drops the site level and returns the two A rows indexed by year. df.xs(2023, level="year") returns the two 2023 rows indexed by site, because the selected level is dropped by default. The full key in the third line returns one number. reset_index() returns a flat table with site and year as ordinary columns, the shape most plotting, regression and export code expects.

Output and how to read it

A MultiIndex prints as a list of tuples followed by names=[...]. In a DataFrame, repeated outer labels are shown once and blanked below, so a row that looks unlabelled belongs to the outer label above it. Check df.index.nlevels to count levels, df.index.names to see their names and df.index.levels for the unique values of each level.

levels can be misleading after you subset. The user guide states that the index keeps unused levels “to avoid a recomputation of the levels”: after df[["foo", "qux"]] the columns still list bar and baz in .levels. Call remove_unused_levels() to rebuild them; the documented result is FrozenList([['foo', 'qux'], ['one', 'two']]). Use get_level_values(0) or get_level_values("second") to see the values actually present, one per row.

Troubleshooting

Symptom Documented cause Fix
UnsortedIndexError: 'Key length (2) was greater than MultiIndex lexsort depth (1)' Range slice on an index that is not lexsorted df = df.sort_index(), then confirm df.index.is_monotonic_increasing
PerformanceWarning and a copy instead of a view Indexing an unsorted MultiIndex Sort the index first
KeyError on df.T["bar"] Bracket selection on columns does not select the outer index level of a transposed frame Use df.T.loc["bar"]
Four rows returned when two were expected A tuple of lists selects a product of level values Use a list of tuples for complete keys
Slice result is not what you intended Only one axis given to .loc Specify both axes, for example df.loc[idx[...], :]
Levels you removed still appear in .levels Unused levels are kept by design remove_unused_levels()
Level names are lost or None after reshaping Names default to None when not given Pass names= or use rename_axis(index=[...]) / set_names
ValueError when building with levels and codes verify_integrity=True checks that levels are unique and consistent with the codes Use a from_* constructor instead of passing levels/codes by hand

A MultiIndex usually arrives as the result of another operation. pandas pivot and pivot_table build row and column hierarchies from long data. pandas melt goes the other way, from wide to long, and pandas concat can stack frames under a new outer index level through its keys. After any of these, a quick look at df.index.names and a sort_index() keep the result predictable. The pandas objects themselves are free and open source; the documentation is at pandas.pydata.org.

Frequently asked questions

What is a MultiIndex in pandas?

It is pandas’ hierarchical index: an array of unique tuples, one tuple per row or column label, with each position in the tuple being a level. It lets one Series or DataFrame be indexed by several keys, such as site and year.

How do I create a pandas MultiIndex?

Use pd.MultiIndex.from_arrays for a list of arrays, from_tuples for a list of tuples, from_product for every combination of several iterables, or from_frame for a DataFrame. Passing a list of arrays as the index of a Series or DataFrame also builds one.

How do I select one level of a MultiIndex?

Use df.xs(value, level="name"), which works on any level by name and drops that level from the result unless you set drop_level=False. For several levels or ranges use df.loc with pd.IndexSlice.

Why do I get UnsortedIndexError?

A range slice was attempted on an index that is not sorted. Call sort_index() and the same slice works, as the pandas user guide demonstrates.

How do I turn a MultiIndex back into columns?

Call df.reset_index(). To move only some levels, pass level=; to discard them, pass drop=True. Assign the result, because inplace is deprecated as of pandas 3.1.0.

Is “pandas multiindex” the same thing as “multiindex pandas”?

Yes. Both phrasings refer to pandas.MultiIndex, the hierarchical index class covered on this page.

Sources

Data: pandas MultiIndex constructors: inputs and documented example sizes

Compares the four pandas MultiIndex constructors by the input each accepts and the number of index tuples in the example given in the official pandas 3.1.1 documentation. Compiled from the pandas user guide and API reference.

Period covered: 2026.

pandas MultiIndex constructors: inputs and documented example sizes
ConstructorInput it takesLevels in docs exampleTuples in docs example
MultiIndex.from_arraysList of arrays, one per level24
MultiIndex.from_tuplesList of tuples28
MultiIndex.from_productList of iterables (all combinations)28
MultiIndex.from_frameDataFrame (columns become levels)24

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about MultiIndex in pandas: Create, Select, Sort and Reset

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →