Skip to content

Python collections Module: Counter, defaultdict, deque, OrderedDict, namedtuple

  • How Counter counts items and supports arithmetic and most_common.
  • How defaultdict auto-initializes missing keys with a factory.
  • How deque gives O(1) appends and pops at both ends, unlike a list.
  • When OrderedDict still earns its place now that plain dicts are ordered.
  • How namedtuple makes lightweight, immutable records.
  • How to choose among these and the built-in containers for a given job.

The collections module provides specialized containers that fill the gaps left by the built-in dict, list, set, and tuple. Counter counts hashable items, defaultdict initializes missing keys automatically, deque is a double-ended queue with fast operations on both ends, OrderedDict is a dict that remembers insertion order (and offers move_to_end), and namedtuple builds tuple subclasses with named fields. Each replaces a small but common pattern you would otherwise write by hand.

Without these types, the same handful of patterns recur as hand-rolled boilerplate: count word frequencies with get, initialize nested dicts with setdefault, build a queue with list.insert(0, ...) which is O(n), and track insertion order with parallel lists. The collections types replace each pattern with a purpose-built container that is shorter, clearer, and often faster.

Counting by hand:

orders = ["shipped", "pending", "shipped", "paid", "shipped"]
counts = {}
for status in orders:
counts[status] = counts.get(status, 0) + 1
print(counts)
# {'shipped': 3, 'pending': 1, 'paid': 1}

The get form works, but Counter says the same thing in one line and adds the operations a hand-rolled dict does not.

Counter is a dict subclass that counts hashable items. Constructing it from an iterable counts every element; most_common(n) returns the top entries; and counters support arithmetic, so you can add and subtract frequency maps directly.

from collections import Counter
orders = ["shipped", "pending", "shipped", "paid", "shipped", "pending"]
status_counts = Counter(orders)
print(status_counts)
# Counter({'shipped': 3, 'pending': 2, 'paid': 1})
print(status_counts.most_common(2))
# [('shipped', 3), ('pending', 2)]
# arithmetic on frequency maps
yesterday = Counter(shipped=5, pending=2)
today = Counter(shipped=3, pending=2, paid=1)
print(yesterday + today)
# Counter({'shipped': 8, 'pending': 4, 'paid': 1})
print(today - Counter(shipped=1))
# Counter({'shipped': 2, 'pending': 2, 'paid': 1})

most_common(2) returns the two most frequent items as (key, count) pairs. Adding counters merges their counts, which is far clearer than looping and adding by hand. Missing keys return zero rather than raising, so status_counts["refunded"] is 0.

defaultdict takes a factory callable and calls it to produce a value for any missing key. The classic use is grouping items into lists: defaultdict(list) turns a loop with setdefault or get into a single append.

from collections import defaultdict
orders = [
("Acme", 1500.0), ("Globex", 800.0), ("Acme", 450.0), ("Globex", 200.0),
]
by_customer = defaultdict(list)
for customer, amount in orders:
by_customer[customer].append(amount)
print(dict(by_customer))
# {'Acme': [1500.0, 450.0], 'Globex': [800.0, 200.0]}
print(sum(by_customer["Acme"]))
# 1950.0
# int as a factory counts, since int() returns 0
counts = defaultdict(int)
for status in ["shipped", "shipped", "paid"]:
counts[status] += 1
print(dict(counts))
# {'shipped': 2, 'paid': 1}

Reading a missing key calls the factory, so by_customer["Acme"] creates the list on first access. defaultdict(int) is the one-line counter; defaultdict(list) is the one-line grouping map.

A deque is a double-ended queue with O(1) append and pop on both ends. A list is O(1) at the right end but O(n) at the left, so a deque is the right choice for a queue or a sliding window where you push at one end and pull from the other.

from collections import deque
queue = deque(["ORD-1", "ORD-2", "ORD-3"])
queue.append("ORD-4") # O(1) push on the right
first = queue.popleft() # O(1) pop from the left
print(first, list(queue))
# ORD-1 ['ORD-2', 'ORD-3', 'ORD-4']
# bounded deque as a rolling history of the last 3 events
history = deque(maxlen=3)
for event in ["created", "paid", "shipped", "refunded"]:
history.append(event)
print(list(history))
# ['paid', 'shipped', 'refunded'] <- oldest dropped automatically

A maxlen deque discards the oldest item when full, which is the cleanest way to keep a fixed-size history. The same shape as a list would need manual trimming on every append.

Since Python 3.7, plain dicts preserve insertion order, so OrderedDict is no longer needed just for order. It still earns its place for move_to_end and popitem(last=False), operations plain dicts do not offer, and for code that must order on Python versions before 3.7.

from collections import OrderedDict
policy = OrderedDict()
policy["shipped"] = 1
policy["pending"] = 2
policy["paid"] = 3
policy.move_to_end("pending") # move pending to the back
print(list(policy))
# ['shipped', 'paid', 'pending']
policy.move_to_end("shipped", last=False) # move shipped to the front
print(list(policy))
# ['shipped', 'paid', 'pending']

move_to_end reorders an entry without reinserting it, which matters for an LRU-style cache where the order encodes recency.

namedtuple builds a tuple subclass with named fields. The instances are immutable and hashable like tuples, but fields are accessed by name, which makes records readable. See the namedtuple feature page for the full treatment.

from collections import namedtuple
Order = namedtuple("Order", ["order_id", "customer", "amount"])
o = Order(1023, "Acme", 42.5)
print(o.customer, o.amount)
# Acme 42.5

OrdersPortal counts orders by status, groups them by customer, and keeps a rolling history of the last two status changes per order, each with a different collections type.

from collections import Counter, defaultdict, deque
events = [
(1023, "shipped"), (1024, "pending"), (1023, "paid"), (1024, "shipped"),
(1025, "pending"), (1023, "shipped"), (1024, "delivered"),
]
# count by status
status_counts = Counter(e[1] for e in events)
print("counts:", status_counts.most_common())
# counts: [('shipped', 3), ('pending', 2), ('paid', 1), ('delivered', 1)]
# rolling history, last 2 per order
history = defaultdict(lambda: deque(maxlen=2))
for order_id, status in events:
history[order_id].append(status)
for order_id, statuses in history.items():
print(f"order {order_id}: {list(statuses)}")
# order 1023: ['paid', 'shipped']
# order 1024: ['shipped', 'delivered']
# order 1025: ['pending']

The defaultdict(lambda: deque(maxlen=2)) factory gives every order a fresh bounded deque on first use, so each order keeps only its two most recent statuses with no manual trimming.

  • Pick the factory that matches the default you want. list for grouping, int for counting, set for collecting unique values. A wrong factory produces a confusing zero-length list or a zero instead of a set.
  • Convert back to a plain dict for serialization. defaultdict, Counter, and OrderedDict are dict subclasses, but JSON serializers and APIs often expect a plain dict. Wrap with dict(...) at the boundary.
  • Measure before swapping a list for a deque. A deque is slower at random access and uses more memory per item. Use it when you actually need fast left-end operations.
  • Using defaultdict where a missing key should be an error. Auto-initialization hides bugs: a typo in a key silently creates a zero instead of raising. Use a plain dict when absence is an error.
  • Expecting deque to be a drop-in list replacement. Slicing a deque returns a list, and indexed assignment is slow. A deque is for queue access patterns, not random access.
  • Reaching for OrderedDict only for order. Plain dicts have been ordered since Python 3.7. Use OrderedDict for move_to_end and popitem(last=False), not just to remember order.
  • Making a namedtuple when you need mutation or defaults. Named tuples are immutable and offer no defaults without extra syntax. A dataclass is the better fit; see dataclasses.
  • Forgetting that Counter arithmetic drops zero and negative counts. Subtraction removes entries whose count reaches zero or below, which is usually what you want but can surprise you.
Container Use it for Avoid when
Counter Counting, frequency maps, most_common You need arbitrary keyed storage, not counts
defaultdict Grouping or counting where missing keys are normal A missing key is a bug you want to surface
deque Queue, stack, sliding window, fixed history Random access or large slices dominate
OrderedDict move_to_end, LRU-style ordering, pre-3.7 order You only need insertion order (use a dict)
namedtuple Small immutable records read by field name You need mutation, defaults, or methods

Counter, defaultdict, deque, OrderedDict, and namedtuple all arrived in early versions and are available in Python 3.9 and later. Since Python 3.7, regular dicts preserve insertion order, which reduced the role of OrderedDict. The examples here run on Python 3.9 and later with no imports beyond collections.

1. Why does defaultdict(int) work as a counter? int() returns 0, so a missing key is initialized to zero before the increment, which is exactly the counting pattern. Any zero-argument callable works as a factory; list returns an empty list, set an empty set.

2. When is a deque faster than a list? On appends and pops at the left end, where a deque is O(1) and a list is O(n). At the right end both are O(1). For random access by index, a list is faster, because a deque does not support O(1) slicing.

3. Why does OrderedDict still exist now that dicts are ordered? For move_to_end and popitem(last=False), which plain dicts lack, and for code that must guarantee order on interpreters before 3.7. If you only need insertion order, a plain dict is enough.

4. Senior scenario: a grouping service using defaultdict(list) grows unbounded memory over days. What is happening and how do you fix it? The dict accumulates one key per distinct value forever, so a high-cardinality field like order id or user id fills memory. Fix it by bounding the structure: use an LRU policy with OrderedDict.move_to_end and popitem(last=False), evict on a size threshold, or aggregate by a lower-cardinality key. The root cause is unbounded grouping, not the factory choice.

  • Counter counts and does arithmetic on frequency maps; most_common ranks entries.
  • defaultdict auto-initializes missing keys with a factory; list groups, int counts.
  • deque is O(1) on both ends and supports a maxlen rolling history.
  • OrderedDict earns its place for move_to_end, not just for order.
  • namedtuple is the immutable, hashable record; use a dataclass when you need mutation.