collections

Six ready-made containers that replace the loops everyone writes by hand: counting (Counter), grouping (defaultdict), queues and sliding windows (deque), records (namedtuple), ordered-dict tricks (OrderedDict) and layered lookups (ChainMap).

Iterators & containersPython 2.4+Live demo
Import
from collections import Counter, deque, defaultdict
import collections
Public API
Counter, deque, defaultdict, OrderedDict, namedtuple, ChainMap, UserDict, UserList, UserString
Speed
deque and defaultdict are written in C (Modules/_collectionsmodule.c); Counter counting uses a C helper too
Dict family
Counter, defaultdict and OrderedDict are dict subclasses — every dict method works on them
Abstract base classes
Iterable, Mapping, Sequence … live in collections.abc (the old aliases in collections were removed in 3.10)

Demo

Live evaluation
Count words and ask for the most common ones.
Try:
Inputs
textstrsome words
ninthow many
Code
from collections import Counter
Counter('the cat and the hat and the bat'.split()).most_common(2)
Result
[('the', 3), ('and', 2)]

most_common orders by count and keeps the first-seen order among equal counts, so in "ties" b beats a only because it appeared first. The deque drops items from the left once maxlen is reached, and a negative maxlen is a ValueError. In the grouping tab an empty word has no first letter: word[0] raises IndexError before defaultdict is even asked.

Members

Functions1
LIVE
collections.namedtuple
namedtuple(typename, field_names, *, rename=False, defaults=None, module=None)
Build a tuple subclass with named fields: readable repr, attribute access, and helpers _make, _asdict, _replace and _fields.
Classes6
LIVE
collections.ChainMap
ChainMap(*maps)
Search several dicts as one: lookups try each mapping in order, while writes and deletes go only to the first.
LIVE
collections.Counter
Counter(iterable=None, /, **kwds)
A dict subclass that counts hashable things: element → count, missing elements count as 0, and counters add, subtract and compare like multisets.
LIVE
collections.defaultdict
defaultdict(default_factory=None, /, [...])
A dict that builds a missing value with default_factory() the first time a key is read — the standard tool for grouping and counting.
LIVE
collections.deque
deque(iterable=(), maxlen=None)
A double-ended queue: O(1) appends and pops at both ends, optional maxlen for a fixed-size buffer.
LIVE
collections.OrderedDict
OrderedDict([items])
A dict subclass with order-aware extras: move_to_end(), popitem(last=False) and equality that compares order. Since 3.7 plain dicts keep order too.
UserDict, UserList, UserString
UserDict([initialdata]) · collections.UserList([list]) · collections.UserString(seq)
Wrapper classes for building your own dict-, list- and str-like types: the real data lives in .data, and every method goes through your overrides.
Methods & attributes14
LIVE
ChainMap.new_child / parents
new_child(m=None, **kwargs) · ChainMap.parents
Push a new mapping in front of a ChainMap (new_child) or get the chain without its first mapping (parents) — nested scopes in two operations.
LIVE
ChainMap pop / popitem / clear
pop(key[, default]) · ChainMap.popitem() · ChainMap.clear()
Removal on a ChainMap only ever touches the first mapping: pop, popitem, clear and del ignore every later map.
LIVE
Counter.elements
elements()
An iterator that repeats each element as many times as its count — zero and negative counts are skipped.
LIVE
Counter.most_common
most_common(n=None)
The n most common elements and their counts, highest first — ties keep the order the elements were first seen.
LIVE
Counter.total
total()
The sum of all counts — negative counts included. New in Python 3.10.
LIVE
Counter.update / subtract
update(iterable=None, /, **kwds) · Counter.subtract(iterable=None, /, **kwds)
Add counts to a Counter in place (update) or take them away (subtract) — from an iterable, a mapping or keyword arguments.
LIVE
deque append / appendleft / pop / popleft
append(x) · deque.appendleft(x) · deque.pop() · deque.popleft()
Add or remove one item at either end of a deque in O(1): append/pop on the right, appendleft/popleft on the left.
LIVE
deque extend / extendleft
extend(iterable) · deque.extendleft(iterable)
Add every item of an iterable to the right end (extend) or the left end (extendleft) — where extendleft reverses the order.
LIVE
deque index / count / insert / remove
index(x[, start[, stop]]) · deque.count(x) · deque.insert(i, x) · deque.remove(value)
The list-style methods of deque: find a position, count matches, insert at a position, remove the first match — all O(n).
LIVE
deque.maxlen
deque.maxlen
The size limit of a bounded deque (None when unbounded). A full bounded deque drops items from the far end — a ready-made sliding window.
LIVE
deque rotate / reverse
rotate(n=1) · deque.reverse()
Rotate a deque n steps to the right (negative n: to the left), or reverse it — both in place.
LIVE
OrderedDict dict methods
keys() · od.values() · od.items() · od.update(...) · od.pop(key[, default]) · od.setdefault(key, default=None) · od.clear() · od.copy() · OrderedDict.fromkeys(iterable, value=None)
The dict methods OrderedDict re-implements to keep its order bookkeeping: keys, values, items, update, pop, setdefault, clear, copy and fromkeys.
LIVE
OrderedDict.move_to_end
move_to_end(key, last=True)
Move an existing key to the end (last=True) or to the front (last=False) of an OrderedDict, keeping its value.
LIVE
OrderedDict.popitem
popitem(last=True)
Remove and return a (key, value) pair from the end (last=True, LIFO) or from the front (last=False, FIFO).

Common patterns

Count anything hashable
Counter takes any iterable; most_common gives the ranking.
from collections import Counter
counts = Counter(words)
counts.most_common(10)
Group rows by a key
defaultdict(list) creates the empty list the first time a key is used.
from collections import defaultdict
by_city = defaultdict(list)
for row in rows:
    by_city[row["city"]].append(row)
FIFO queue
append on the right, popleft from the left — both O(1).
from collections import deque
queue = deque()
queue.append(job)
next_job = queue.popleft()
Keep the last N items
A bounded deque discards from the opposite end automatically.
from collections import deque
recent = deque(maxlen=100)
for event in events:
    recent.append(event)
A lightweight record type
namedtuple gives a tuple with field names and a readable repr.
from collections import namedtuple
Point = namedtuple('Point', 'x y')
p = Point(3, 4)
p.x + p.y

Examples

1. Count letters
from collections import Counter Counter('mississippi')
Returns
Counter({'i': 4, 's': 4, 'p': 2, 'm': 1})
2. Missing keys count as zero
from collections import Counter Counter('abc')['z']
Returns
0
3. Queue from both ends
from collections import deque d = deque([1, 2, 3]) d.appendleft(0) d.pop() d
Returns
deque([0, 1, 2])
4. Group with defaultdict
from collections import defaultdict d = defaultdict(list) d['fruit'].append('apple') d
Returns
defaultdict(<class 'list'>, {'fruit': ['apple']})
5. Named fields on a tuple
from collections import namedtuple Point = namedtuple('Point', 'x y') Point(3, 4)
Returns
Point(x=3, y=4)
6. Layered settings
from collections import ChainMap ChainMap({'color': 'red'}, {'color': 'blue', 'size': 'M'})['color']
Returns
'red'
7. OrderedDict equality is order-sensitive
from collections import OrderedDict OrderedDict(a=1, b=2) == OrderedDict(b=2, a=1)
Returns
False

Pitfalls

1. Importing the abstract base classes from collections
Mapping, Iterable, Sequence and friends moved to collections.abc; the old aliases were removed in Python 3.10.
collections.Mapping
import collections
collections.Mapping
AttributeError: module 'collections' has no attribute 'Mapping'
collections.abc
import collections.abc
isinstance({}, collections.abc.Mapping)
True
2. Reading a defaultdict creates keys
d[key] on a missing key inserts the default. Use "in" or .get() to look without inserting.
d[key] to check
from collections import defaultdict
d = defaultdict(list)
if d['ghost']:
    pass
d
defaultdict(<class 'list'>, {'ghost': []})
'in' to check
from collections import defaultdict
d = defaultdict(list)
if 'ghost' in d:
    pass
d
defaultdict(<class 'list'>, {})
3. Using a list as a queue
list.pop(0) shifts every remaining item; deque.popleft() does not. The results are the same, the cost is not.
list.pop(0)
queue = [1, 2, 3]
queue.pop(0)
1
deque.popleft()
from collections import deque
queue = deque([1, 2, 3])
queue.popleft()
1

When to use

Use it
  • Counting and ranking things → Counter
  • Building dicts of lists or sets → defaultdict
  • Queues, stacks and "last N" buffers → deque
  • Small immutable records → namedtuple
  • Layered configuration or scopes → ChainMap
Reach for something else
  • Records that need defaults, type hints and methods → dataclasses (or typing.NamedTuple)
  • Random access into the middle of a long sequence → list (deque indexing is O(n) in the middle)
  • Priority queues → heapq; thread-to-thread queues → queue.Queue

Notes

CPython impl
Lib/collections/__init__.py (Counter, OrderedDict, namedtuple, ChainMap, UserDict/List/String) plus the C module Modules/_collectionsmodule.c (deque, defaultdict, the Counter counting helper)
dict subclasses
Counter, defaultdict and OrderedDict are dict subclasses; ChainMap is a MutableMapping that wraps several dicts
collections.abc
The abstract base classes (Mapping, Sequence, Iterable …) live in collections.abc

FAQ

A standard-library module of specialized container types: Counter (counting), deque (fast double-ended queue), defaultdict (dict with automatic default values), OrderedDict (dict with reordering methods), namedtuple (tuples with named fields), ChainMap (several dicts searched as one) and UserDict/UserList/UserString (base classes for custom containers).