ZetCode

Pandas Index

last modified November 17, 2026 Python 3.15

Every Series and DataFrame has an index: a list of labels attached to the rows. In plain words, a label is a name you can use to point at a row, the way a person's name points at the person rather than their position in a queue. The index is printed in the leftmost column of every DataFrame and is not one of the data columns.

Labels make selection and arithmetic clearer. You can ask for the row named Prague instead of the second row, and pandas can line up two Series by their labels when adding them. Positional selection by row number is covered in the Pandas iloc tutorial, while label-based selection is covered in the Pandas loc tutorial.

The examples below were verified with pandas 3.1.1.

The default integer index

If we do not supply an index, pandas creates one automatically. For a table with two rows it is a RangeIndex, a compact way of storing the integers from 0 up to but not including the number of rows, stepping by one.

index_default.py
import pandas as pd

df = pd.DataFrame({'name': ['Alice', 'Bob'], 'age': [25, 32]})
print(df.index)

The output describes the range directly: it starts at 0, stops at 2, and uses a step of 1, which yields the labels 0 and 1.

$ python index_default.py
RangeIndex(start=0, stop=2, step=1)

set_index

The set_index method turns an existing column into the index. Here the city names become labels, so each row is identified by its city rather than by a number. The chosen column disappears from the data and its name becomes the name of the index.

index_set.py
import pandas as pd

df = pd.DataFrame({'city': ['Bratislava', 'Prague'], 'population': [437000, 1300000]})
indexed = df.set_index('city')
print(indexed)

The header line now shows only population, and the city names sit to its left as row labels. That makes a subsequent lookup by city natural.

$ python index_set.py
            population
city                  
Bratislava      437000
Prague         1300000

reset_index

The reset_index method moves the index back into a regular column and restores the default integer index. By default the old labels become a column named after the index; with drop=True they are discarded instead.

index_reset.py
import pandas as pd

df = pd.DataFrame({'city': ['Bratislava', 'Prague'], 'population': [437000, 1300000]})
indexed = df.set_index('city')

print(indexed.reset_index())
print()
print(indexed.reset_index(drop=True))

The first table has a city column again. The second has only population, because drop=True threw the city labels away. This is often the final step before writing a DataFrame to a file that should not contain an extra index column.

$ python index_reset.py
         city  population
0  Bratislava      437000
1      Prague     1300000

   population
0      437000
1     1300000

reindex

The reindex method builds a new object with the labels you specify, rearranging existing rows and inserting missing ones. A label that has no data gets NaN, which stands for "not a number" and marks a missing value. Because the result now contains a real gap, its integer values are shown as decimals.

index_reindex.py
import pandas as pd

s = pd.Series([10, 20, 30], index=['a', 'b', 'c'])
print(s.reindex(['a', 'b', 'd', 'c']))

The rows appear in the requested order: a, b, the new label d with NaN, then c. The original Series is unchanged.

$ python index_reindex.py
a    10.0
b    20.0
d     NaN
c    30.0
dtype: float64

sort_index

The sort_index method arranges rows by their labels rather than by their values. It works with text labels in alphabetical order and with numeric labels in ascending order.

index_sort.py
import pandas as pd

s = pd.Series([10, 20, 30], index=['c', 'a', 'b'])
print(s.sort_index())

The rows now read a, b, c. Notice that each value stays attached to its own label: 20 moves with a, and 10 moves with c.

$ python index_sort.py
a    20
b    30
c    10
dtype: int64

Duplicate indexes

An index does not have to contain unique labels. If two rows share a label, selecting that label returns every matching row rather than a single value. This can be useful for repeated measurements, but it means the result of a lookup is a Series again.

index_dup.py
import pandas as pd

s = pd.Series([10, 20, 30], index=['a', 'a', 'b'])
print(s)
print()
print(s['a'])

The label a appears twice, so s['a'] returns both 10 and 20. Operations that require unique labels may fail on such an index, so check for duplicates before relying on them.

$ python index_dup.py
a    10
a    20
b    30
dtype: int64

a    10
a    20
dtype: int64

Index alignment in arithmetic

When two Series are added, pandas matches values by their labels, a behaviour called alignment. A label present in only one Series produces NaN in the result, because there is no partner value to compute with. This protects you from accidentally combining unrelated rows.

index_align.py
import pandas as pd

s1 = pd.Series([1, 2, 3], index=['a', 'b', 'c'])
s2 = pd.Series([10, 20], index=['b', 'c'])
print(s1 + s2)

The labels b and c are in both Series, so their values are added: 2 plus 10 is 12, and 3 plus 20 is 23. The label a exists only in s1, so its result is NaN.

$ python index_align.py
a     NaN
b    12.0
c    23.0
dtype: float64

Source

Pandas Indexing and selecting data Documentation, Pandas DataFrame.set_index Documentation, and Pandas Index Documentation

In this article we have explained the index, created a default integer index, replaced it with set_index, undone that with reset_index, changed labels with reindex and sort_index, and seen how duplicate labels and alignment behave in arithmetic. To select by label or by position see the Pandas loc tutorial and the Pandas iloc tutorial.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Pandas tutorials.