Python collections Module: Counter, defaultdict, deque, OrderedDict, namedtuple
What you’ll learn
Section titled “What you’ll learn”- How
Countercounts items and supports arithmetic andmost_common. - How
defaultdictauto-initializes missing keys with a factory. - How
dequegives O(1) appends and pops at both ends, unlike a list. - When
OrderedDictstill earns its place now that plain dicts are ordered. - How
namedtuplemakes lightweight, immutable records. - How to choose among these and the built-in containers for a given job.
Summary
Section titled “Summary”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.
The problem it solves
Section titled “The problem it solves”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) + 1print(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.
How it works
Section titled “How it works”Counter
Section titled “Counter”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 mapsyesterday = 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
Section titled “defaultdict”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 0counts = defaultdict(int)for status in ["shipped", "shipped", "paid"]: counts[status] += 1print(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 rightfirst = queue.popleft() # O(1) pop from the leftprint(first, list(queue))# ORD-1 ['ORD-2', 'ORD-3', 'ORD-4']
# bounded deque as a rolling history of the last 3 eventshistory = deque(maxlen=3)for event in ["created", "paid", "shipped", "refunded"]: history.append(event)print(list(history))# ['paid', 'shipped', 'refunded'] <- oldest dropped automaticallyA 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.
OrderedDict
Section titled “OrderedDict”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"] = 1policy["pending"] = 2policy["paid"] = 3policy.move_to_end("pending") # move pending to the backprint(list(policy))# ['shipped', 'paid', 'pending']policy.move_to_end("shipped", last=False) # move shipped to the frontprint(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
Section titled “namedtuple”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.5Realistic example
Section titled “Realistic example”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 statusstatus_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 orderhistory = 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.
Production patterns
Section titled “Production patterns”- Pick the factory that matches the default you want.
listfor grouping,intfor counting,setfor 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, andOrderedDictare dict subclasses, but JSON serializers and APIs often expect a plain dict. Wrap withdict(...)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.
Common mistakes
Section titled “Common mistakes”- Using
defaultdictwhere 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
dequeto 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
OrderedDictonly for order. Plain dicts have been ordered since Python 3.7. UseOrderedDictformove_to_endandpopitem(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
Counterarithmetic drops zero and negative counts. Subtraction removes entries whose count reaches zero or below, which is usually what you want but can surprise you.
When to use it and when not to
Section titled “When to use it and when not to”| 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 |
Compatibility
Section titled “Compatibility”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.
Interview questions
Section titled “Interview questions”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.
Key takeaways
Section titled “Key takeaways”Countercounts and does arithmetic on frequency maps;most_commonranks entries.defaultdictauto-initializes missing keys with a factory;listgroups,intcounts.dequeis O(1) on both ends and supports amaxlenrolling history.OrderedDictearns its place formove_to_end, not just for order.namedtupleis the immutable, hashable record; use a dataclass when you need mutation.
Related pages
Section titled “Related pages”- deque — the full deque feature page.
- namedtuple — the full namedtuple feature page.
- ordereddict — the full OrderedDict feature page.
- dataclasses — mutable, defaulted records.
- dictionaries — the built-in dict these types extend.
Official references
Section titled “Official references”- Python 3 —
collectionsmodule — Counter, defaultdict, deque, OrderedDict, namedtuple. - Python 3 —
collections.Counterexamples — patterns and recipes. - Python 3 —
collections.dequerecipes — bounded histories and rotating queues.