ZetCode

Pandas Iterating

last modified November 17, 2026 Python 3.15

Although Pandas is built around whole-column operations, there are times when we genuinely need to walk through rows or columns one at a time: printing a report, calling a function that accepts a single record, or inspecting data while debugging. Pandas offers several iterators for these situations, and they are not equally good.

This article compares iterrows, itertuples, items and to_dict, and explains when each is appropriate. Remember that vectorized operations are almost always faster for calculations on entire columns; iteration is a tool for the cases that cannot be expressed that way.

iterrows yields a Series per row

The iterrows method produces pairs of an index label and a row. The row is a Series, which is convenient to index by column name but carries a cost: a Series has one data type, so values from differently typed columns are upcast to a common type that can hold them all. An integer column can therefore turn into floating-point numbers inside the row.

iterrows.py
import pandas as pd

df = pd.DataFrame({'a': [1, 2, 3], 'b': [1.5, 2.5, 3.5]})
index, row = next(df.iterrows())
print("column b dtype:", df['b'].dtype)
print("row dtype:", row.dtype)
print("row['a']:", row['a'], type(row['a']).__name__)

Column b is float64 in the DataFrame, and the row we fetched is a float64 Series too. Because the row must hold both columns in one type, the integer 1 from column a arrives as 1.0, a float64 value. This dtype loss is the main reason iterrows is usually the wrong tool; it also tends to be slow because it builds a Series for every row.

$ python iterrows.py
column b dtype: float64
row dtype: float64
row['a']: 1.0 float64

itertuples yields named tuples

The itertuples method yields a named tuple for each row: a small, immutable object whose fields are read by name, such as row.name. It does not build a Series per row, so it is much faster than iterrows and keeps each column's original type. By default the first field is the index label; passing index=False removes it.

itertuples.py
import pandas as pd

df = pd.DataFrame({'name': ['a', 'b', 'c'], 'score': [10, 20, 30]})
for row in df.itertuples(index=False):
    print(row.name, row.score, type(row).__name__)

Each row is an instance of a generated named-tuple class called Pandas, and its name and score fields are read directly. This is the iterator to choose when a real Python loop over rows is unavoidable; if column names are not valid Python identifiers, Pandas renames the corresponding fields and warns, which is another sign that an array-based approach may be better.

$ python itertuples.py
a 10 Pandas
b 20 Pandas
c 30 Pandas

Iterating over columns with items

A DataFrame can also be walked column by column. The items method yields pairs of a column name and a Series holding that column, which is handy when each column needs separate treatment. The older name iteritems was deprecated in Pandas 2.0 and has been removed in Pandas 3.0, so new code should use items.

iter_columns.py
import pandas as pd

df = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
for name, column in df.items():
    print(name, column.tolist())
print('has iteritems:', hasattr(df, 'iteritems'))

The loop prints the name a with its values and then the name b with its values. The final line confirms that on the Pandas 3.1.1 version used here iteritems no longer exists, so calling it would raise an error. Use items for portable code.

$ python iter_columns.py
a [1, 2]
b [3, 4]
has iteritems: False

Iterating over a Series with items

The same method name works on a Series, where it pairs each index label with its value. This is the closest thing to iterating over a plain dictionary, and it preserves the label, which a plain loop over the values would discard. It is useful for small Series when you need both parts of each entry.

series_items.py
import pandas as pd

s = pd.Series([10, 20, 30], index=['x', 'y', 'z'])
for label, value in s.items():
    print(label, value)

The three index labels x, y and z are printed alongside their values. The values here are ordinary Python integers, and unlike iterrows there is no row-wide dtype conversion to worry about.

$ python series_items.py
x 10
y 20
z 30

Exporting rows with to_dict

Sometimes the goal is not to iterate in Python at all but to hand the rows to another library that expects a list of dictionaries. The to_dict method with the argument 'records' converts each row into a dictionary keyed by column name, dropping the index. The result is a plain Python list, not a Pandas object.

to_dict_records.py
import pandas as pd

df = pd.DataFrame({'name': ['a', 'b'], 'score': [10, 20]})
print(df.to_dict('records'))

Two dictionaries are produced, one per row, with name and score as keys and native Python values. This is a common format for JSON APIs and templating engines. If you only need to loop over the rows yourself, itertuples is usually the better choice because it does not build a dictionary for every row.

$ python to_dict_records.py
[{'name': 'a', 'score': 10}, {'name': 'b', 'score': 20}]

Choosing the right tool

The table below collects the advice from the sections above. It is a starting point rather than a strict rule: the shape of the data and the code that must consume it also matter. The central point is that whole-column arithmetic should be the default, with iteration reserved for genuine per-record work.

GoalPreferred tool
Arithmetic or logic on whole columnsVectorised operations, np.where
One derived value per row in a Python loopitertuples
Quickly inspect rows while debuggingiterrows, accepting the dtype loss
Walk the columns of a DataFrameDataFrame.items
Walk the labels and values of a SeriesSeries.items
Pass rows to an API that needs dictionariesto_dict('records')

Source

Pandas DataFrame.iterrows Documentation, Pandas DataFrame.itertuples Documentation, Pandas DataFrame.items Documentation, and Pandas DataFrame.to_dict Documentation

In this article we have compared the main ways to iterate over Pandas data: iterrows and its dtype loss, faster itertuples rows, items for columns and for Series, and to_dict('records') for exporting rows. For calculations that do not need a loop, see Pandas vectorization and performance, and for adding derived columns without iterating see Pandas apply, map and transform.

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.