How it works
namedtuple creates a tuple subclass with named fields. Instances support attribute access, indexing and unpacking. Their field bindings cannot be reassigned, although a mutable object stored in a field can still change.
Choose a named tuple for small fixed-shape records. A dataclass may be clearer when records need defaults, validation methods or controlled mutable fields. typing.NamedTuple offers a class-style declaration with annotations.
Choices and common mistakes
_replace returns a new record; it does not edit the existing record. The underscore is part of this documented public API.
Tuple immutability does not make nested lists immutable. Store immutable field values when you need an entirely immutable record.
Try it yourself
Create a named tuple for a reading with value and unit. Unpack it, then create a modified copy and confirm that the original is unchanged.
Syntax
from collections import namedtuple
Point = namedtuple("Point", ["x", "y"])
point = Point(2, 3)Examples
Read named coordinates
Make the meaning of each tuple position explicit.
from collections import namedtuple
Point = namedtuple("Point", ["x", "y"])
point = Point(2, 3)
print(point.x + point.y)
x, y = point
print(x, y)- Point is the generated class; calling it creates a record. Attribute access names the coordinate being read.
- Unpacking still works because the record is a tuple subclass. The two names receive its positional values.
- Named fields make geometry or row records clearer than scattered numeric indexes.
- Expected output: 5 2 3
Create a changed record
Replace one field without changing the original.
from collections import namedtuple
Point = namedtuple("Point", ["x", "y"])
original = Point(2, 3)
moved = original._replace(x=8)
print(original)
print(moved)- _replace copies the fields into a new record and substitutes x. The y field retains its value.
- The two printed records show that original remains unchanged. Reassigning original.x would fail.
- This supports workflows where previous states should remain available for comparison.
- Expected output: Point(x=2, y=3) Point(x=8, y=3)
Expose the shallow boundary
See why immutable fields can still refer to mutable objects.
from collections import namedtuple
Group = namedtuple("Group", ["members"])
group = Group(["John"])
group.members.append("James")
print(group.members)- The members field continues to refer to the same list. append changes that list rather than rebinding the field.
- The successful mutation shows that the container’s immutability is shallow.
- Use a tuple of member names instead when downstream code must not modify the nested collection.
- Expected output: ['John', 'James']
Best practices
- _replace returns a new record; it does not edit the existing record. The underscore is part of this documented public API.
- Tuple immutability does not make nested lists immutable. Store immutable field values when you need an entirely immutable record.
Runtime & versions
Python interpreter. Feature availability depends on the language and runtime version used by your project; consult the official reference below.
Python language reference