Row-wise processing
Read row values in a loop while retaining readable field access.
Pandas · Module
df.itertuples
Iterate through DataFrame rows as namedtuples, optionally including the index and choosing a custom tuple type name. Set name=None for ordinary tuples.
How it works
Call itertuples() to obtain an iterator whose rows expose column values as tuple fields. By default each row is a namedtuple named Pandas and starts with the index; disable the index or provide a custom tuple name when needed.
Syntax
DataFrame.itertuples(index=True, name='Pandas')Parameters
| Name | Type | Description |
|---|---|---|
index | bool, default True | Whether to include the index as the first tuple element; defaults to True. |
name | str or None, default "Pandas" | The name assigned to returned namedtuples, or None for regular tuples; defaults to "Pandas". |
Returns
An iterator producing one namedtuple for each DataFrame row; the first field may be the index, followed by column values.
Key points
- The method provides row-wise iteration through namedtuples.
- Use name=None when ordinary tuples are preferable to namedtuples.
- Namedtuple fields are derived from column labels when those labels can be used as fields.
- The default index=True places the DataFrame index before column values.
- The name parameter controls the generated tuple type name or switches to regular tuples.
- The return value is an iterator, so rows are produced lazily during iteration.
Common mistakes
- Field names may not match the original column labels: invalid, duplicate, or underscore-prefixed labels are replaced with positional names.
- Do not rely on attribute access preserving every column label; use positional fields when labels require renaming.
Example: Iterate over rows as namedtuples
import pandas as pd
df = pd.DataFrame(
{"num_legs": [4, 2], "num_wings": [0, 2]},
index=["dog", "hawk"],
)
for row in df.itertuples(index=False, name="Animal"):
print(row.num_legs, row.num_wings)Iterates over rows without including the index and yields namedtuples called Animal.
When to use it
Index-free records
Exclude the index when exporting or passing row values to another routine.
Positional iteration
Use ordinary tuples for lightweight positional processing.
Interview questions
QWhat does DataFrame.itertuples() return?
itertuples() returns an iterator that produces one namedtuple per DataFrame row. The index is included as the first field by default, followed by column values.
Follow-up: How would you produce ordinary tuples without the index? Use df.itertuples(index=False, name=None).
QHow do index and name affect the output?
Set index=False to omit the index field. Set name=None to yield regular tuples instead of namedtuples.
Follow-up: What happens if name is a string? Each yielded namedtuple uses that string as its type name.
QWhen can namedtuple field names differ from DataFrame columns?
Column labels normally become namedtuple fields, but labels that are invalid Python identifiers, repeated, or begin with an underscore are renamed to positional names. Code requiring stable attribute names should account for that behavior.
Follow-up: Why might positional access be safer for arbitrary schemas? Column labels can be transformed, so positions avoid depending on generated field names.
Related
DataFrame.iterrowsDataFrame.itemsDataFrame.__iter__