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.
MultiIndex.from_arraystakes a list of arrays, one array per level. The API reference example isarrays = [[1, 1, 2, 2], ["red", "blue", "red", "blue"]]followed bypd.MultiIndex.from_arrays(arrays, names=("number", "color")), which returnsMultiIndex([(1, 'red'), (1, 'blue'), (2, 'red'), (2, 'blue')], names=['number', 'color']).MultiIndex.from_tuplestakes a list of tuples. The user guide builds it withtuples = list(zip(*arrays))and thenpd.MultiIndex.from_tuples(tuples, names=["first", "second"]).MultiIndex.from_producttakes a list of iterables and builds every combination. The user guide example isiterables = [["bar", "baz", "foo", "qux"], ["one", "two"]]andpd.MultiIndex.from_product(iterables, names=["first", "second"]), which yields the same eight tuples as thefrom_tuplesexample.MultiIndex.from_frametakes a DataFrame and uses its columns as levels. It is described as the complement ofto_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 framedf.T["bar"]raisesKeyError; usedf.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=Falsekeeps it.df.xs(("one", "bar"), level=("second", "first"), axis=1)selects on several levels at once; the user guide shows this on columns withaxis=1.pd.IndexSlicegives “a more natural syntax using:, rather than usingslice(None)“. The documented form isidx = pd.IndexSlicethendfmi.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 theswaplevelmethod, 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 isDataFrame.reset_index(level=None, *, drop=False, inplace=no_default, col_level=0, col_fill='', allow_duplicates=False, names=None). Passlevel="class"to move only that level and keep the rest as the index; each removed level becomes a column. For a MultiIndex,namesmust be a list with one entry per level.drop=Truediscards the levels instead.- The
inplaceargument ofreset_indexis 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, anddroplevelremoves 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 |
Related reshaping tools
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
- pandas documentation, MultiIndex / advanced indexing (pandas 3.1.1), read 2026-11-14.
- pandas documentation, pandas.MultiIndex API reference (pandas 3.1.1), read 2026-11-14.
- pandas documentation, pandas.DataFrame.reset_index (pandas 3.1.1), read 2026-11-14.
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.
| Constructor | Input it takes | Levels in docs example | Tuples in docs example |
|---|---|---|---|
| MultiIndex.from_arrays | List of arrays, one per level | 2 | 4 |
| MultiIndex.from_tuples | List of tuples | 2 | 8 |
| MultiIndex.from_product | List of iterables (all combinations) | 2 | 8 |
| MultiIndex.from_frame | DataFrame (columns become levels) | 2 | 4 |
Sources
- pandas user guide: MultiIndex / advanced indexing (pandas 3.1.1) (accessed 2026-11-14)
- pandas.MultiIndex API reference (pandas 3.1.1) (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







