Counting Items with collections.Counter

Intermediate

A dictionary is a good choice when a key should map to one current value. Counting is a more specific job: each item may appear many times, and you want to keep its running total. collections.Counter is a dictionary subclass built for tallying hashable items without writing the counting loop yourself.

Build a counter from data

Pass an iterable to Counter to count each hashable item. You can also initialize one from a mapping of items to existing counts. The keys are the distinct items; their values are the counts. Strings are iterables too, so Counter('level') counts characters, not words.

from collections import Counter
counts = Counter("cocoa")
print(counts['o'])
print(counts['c'])?

Looking up a missing key returns 0 rather than raising KeyError. That lookup does not insert the missing key into the counter. This makes it convenient to ask for a count without first checking membership.

Find the most common items

most_common(n) returns up to n (item, count) pairs from highest count to lowest. With equal counts, it preserves the order in which those items were first encountered. Omit n to get all items in that order by count. This method ranks existing counts; it does not change them.

from collections import Counter
counts = Counter("banana")
print(counts.most_common(2))?

Add counts and subtract counts

Counter.update() adds counts from an iterable or mapping; unlike dict.update(), a mapping does not replace the old counts. Counter.subtract() subtracts counts but keeps zero and negative results. Setting a count to zero also does not remove that key; use del when you need to remove the entry.

from collections import Counter
counts = Counter(apple=2)
counts.update({"apple": 3})
print(counts["apple"])?

Expand counts and total them

total() adds the counts together. elements() returns an iterator that repeats each item according to its count, but it ignores zero and negative counts. Because this operation repeats items, counts used with elements() should be integers. It is not the same as iterating over the distinct keys.

from collections import Counter
counts = Counter(a=2, b=0, c=-1)
print(list(counts.elements()))?

Combine counters as multisets

Counter supports multiset-style operations. Addition combines counts, subtraction keeps only positive differences, intersection (&) keeps the smaller count for each item, and union (|) keeps the larger count. These operators discard results that are zero or negative; this differs from the subtract() method, which preserves those results. The symmetric-difference operator added in Python 3.15 is tracked separately because it has not been run on the available local interpreter.

from collections import Counter
left = Counter(red=4, blue=1)
right = Counter(red=2, blue=3)
print(left & right)?