Skip to content

Effortlessly Understanding Python's namedtuple


Using namedtuple to Write Pythonic Code

The Python collections module provides a factory function called namedtuple(), which is specially designed to make your code more Pythonic when you’re working with tuples. With namedtuple(), you can create immutable sequence types that allow you to access their values using descriptive field names and the dot notation instead of unclear integer indices.

Creating Tuple-Like Classes With namedtuple()

To create a namedtuple class, you can use the namedtuple() function provided by the collections module.

from collections import namedtuple
# Define a namedtuple class called Point
Point = namedtuple('Point', ['x', 'y'])
# Create an instance of the Point class
p = Point(2, 3)
# Access the values using field names
print(p.x) # Output: 2
print(p.y) # Output: 3

Providing Required Arguments to namedtuple()

When creating a namedtuple class, you need to provide a name for the class and a sequence of field names. The field names can be provided as a list or as a space-separated string.

# Providing field names as a list
Point = namedtuple('Point', ['x', 'y'])
# Providing field names as a space-separated string
Point = namedtuple('Point', 'x y')

Using Optional Arguments With namedtuple()

The namedtuple() function also accepts optional arguments to customize the behavior of the resulting namedtuple class. Some of these optional arguments include:

  • rename - If set to True, it allows duplicate names to be appended with an underscore followed by a number to avoid conflicts.
  • defaults - It allows you to provide default values for fields.
  • module - It specifies the module name to associate with the resulting namedtuple class for better debugging information.
# Example using optional arguments
Person = namedtuple('Person', ['name', 'age'], defaults=['Unknown', 0], rename=True)
p = Person(age=25)
print(p) # Output: Person(name='Unknown', age=25)

Exploring Additional Features of namedtuple Classes

namedtuple classes come with some useful features that make working with them even more convenient.

Creating namedtuple Instances From Iterables

You can create instances of a namedtuple class directly from an iterable, such as a list or tuple, by using the _make() method.

Person = namedtuple('Person', ['name', 'age'])
data = ['John', 30]
p = Person._make(data)
print(p) # Output: Person(name='John', age=30)

Converting namedtuple Instances Into Dictionaries

You can convert a namedtuple instance into a dictionary using the _asdict() method. This can be useful if you need to work with your data as a dictionary or if you want to serialize it.

Person = namedtuple('Person', ['name', 'age'])
p = Person('John', 30)
data_dict = p._asdict()
print(data_dict) # Output: {'name': 'John', 'age': 30}

Replacing Fields in Existing namedtuple Instances

namedtuple instances are immutable, which means that you can’t modify their values directly. However, you can replace fields with new values to create a new instance using the _replace() method.

Person = namedtuple('Person', ['name', 'age'])
p1 = Person('John', 30)
p2 = p1._replace(age=40)
print(p1) # Output: Person(name='John', age=30)
print(p2) # Output: Person(name='John', age=40)

Exploring Additional namedtuple Attributes

namedtuple classes come with a few additional attributes that can provide useful information, such as:

  • __doc__ - The docstring for the class.
  • _fields - A tuple of field names.
  • _source - The original source code used to create the namedtuple class.
Person = namedtuple('Person', ['name', 'age'])
print(Person.__doc__) # Output: Person(name, age)
print(Person._fields) # Output: ('name', 'age')
print(Person._source) # Output: NamedTuple('Person', [('name', 'age')])

Writing Pythonic Code With namedtuple

One of the main advantages of using namedtuple is that it allows you to write more Pythonic code. Here are some examples of how you can achieve this.

Using Field Names Instead of Indices

Instead of using unclear integer indices, you can use descriptive field names to access the values of a namedtuple instance.

Person = namedtuple('Person', ['name', 'age'])
p = Person('John', 30)
# Access values using field names
print( # Output: John
print(p.age) # Output: 30

Returning Multiple Named Values From Functions

If you need to return multiple values from a function, you can use a namedtuple instance to provide better clarity and readability to your code.

Person = namedtuple('Person', ['name', 'age'])
def get_person():
return Person('John', 30)
p = get_person()
# Access the returned values
print( # Output: John
print(p.age) # Output: 30

Reducing the Number of Arguments to Functions

When you have a large number of arguments to pass to a function, you can use a namedtuple instance to reduce the number of arguments by providing them as a single argument.

Point = namedtuple('Point', ['x', 'y'])
def calculate_distance(p1, p2):
return ((p2.x - p1.x) ** 2 + (p2.y - p1.y) ** 2) ** 0.5
p1 = Point(0, 0)
p2 = Point(3, 4)
distance = calculate_distance(p1, p2)
print(distance) # Output: 5.0

Reading Tabular Data From Files and Databases

namedtuple instances can be helpful when you need to read tabular data from files or databases. You can create a namedtuple class that represents each row of the data, making it easier to access the values using field names.

import csv
from collections import namedtuple
# Define a namedtuple class for the data rows
DataPoint = namedtuple('DataPoint', ['date', 'amount', 'description'])
# Read the data from a CSV file
with open('data.csv') as csvfile:
reader = csv.reader(csvfile)
next(reader) # Skip the header row
data = [DataPoint(*row) for row in reader]
# Access the data values using field names
for dp in data:
print(, dp.amount, dp.description)

Using namedtuple vs Other Data Structures

When deciding whether to use a namedtuple or another data structure, consider the specific requirements of your code. Here are some comparisons between namedtuple and other popular data structures.

namedtuple vs Dictionary

namedtuple instances are similar to dictionaries, but with a more concise syntax and the advantage of being immutable. Use a namedtuple if you have a fixed set of fields and need a compact representation of your data.

namedtuple vs Data Class

Python 3.7 introduced the dataclass decorator, which allows you to create classes with automatically generated special methods and default values for fields. Use a data class when you need more flexibility and control over your class structure.

namedtuple vs typing.NamedTuple

The typing module in Python provides a NamedTuple class that is similar to namedtuple, but with more advanced type annotations. Use NamedTuple if you need to specify types for the fields of your namedtuple class.

Subclassing namedtuple Classes

You can subclass a namedtuple class to add new functionality or override certain methods. This allows you to customize the behavior of the class to fit your specific needs.

from collections import namedtuple
# Define a subclass of the Point namedtuple class
class Point(namedtuple('Point', ['x', 'y'])):
def distance_from_origin(self):
return (self.x ** 2 + self.y ** 2) ** 0.5
p = Point(3, 4)
distance = p.distance_from_origin()
print(distance) # Output: 5.0

Measuring Creation Time: tuple vs namedtuple

namedtuple instances are more memory-efficient than regular tuples because they do not store attribute names. Additionally, creating a namedtuple instance is usually faster than creating and unpacking a regular tuple.


Using namedtuple allows you to write more Pythonic and readable code when working with tuples. It provides a concise and intuitive syntax for creating tuple-like classes with named fields. namedtuple instances can be used to replace regular tuples in your code, making it more clear and maintainable.

To become proficient with namedtuple, it’s important to practice writing code that utilizes its features. Experiment with creating namedtuple classes, accessing fields using their names, and using the provided methods to manipulate instances. By incorporating namedtuple into your Python code, you can improve the clarity and readability of your codebase.