Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Comparison Key Function Explained

Learn how Python's comparison key function works with sorting, min(), and max(), including examples using lambda, itemgetter, and attrgetter.

~5 min readPython
#python#sorting#key-function#lambda
Diagram showing a Python list of objects on the left, each with a highlighted field, an arrow representing the key function extracting that field into a separate list, and a sorted list on the right.

In Python, a key function (sometimes called a comparison key function) is a callable that Python applies to each element before sorting or selection. It transforms every item into a comparable value, and that value is used for ordering. Instead of writing a custom two-argument comparison function and wrapping it with functools.cmp_to_key, you provide a key function that takes one item and returns a sortable key. This is often simpler, faster, and more readable.

How Sorting Uses the Key Function

When you call list.sort() or the built-in sorted(), Python compares elements directly by default. That works for numbers and strings, but fails for objects that do not define an ordering. The key parameter changes the behavior: Python calls the key function on each element exactly once, stores the returned key, and sorts based on those keys. The original elements are never compared directly.

python
words = ['banana', 'apple', 'cherry', 'date'] sorted_words = sorted(words, key=len) print(sorted_words) # ['date', 'apple', 'banana', 'cherry']

Here len is the key function. Python computes len(word) for each word and sorts by the resulting integer. The original strings are preserved; only the ordering changes. This is the core idea behind the key function: it decouples the comparison value from the element itself.

The key function is called once per element, not once per comparison. This is a significant performance advantage over a custom comparison function wrapped with functools.cmp_to_key, which is invoked repeatedly during the sort. For a list of n elements, the key function runs n times, while a comparison function might run O(n log n) times. That difference matters for large collections.

Using Key with min() and max()

The same key function works with min() and max(). Instead of returning the smallest or largest element directly, these functions use the key to determine which element has the smallest or largest key value.

python
students = [ {'name': 'Alice', 'grade': 85}, {'name': 'Bob', 'grade': 92}, {'name': 'Charlie', 'grade': 78}, ] best = max(students, key=lambda s: s['grade']) print(best['name']) # Bob

The lambda returns the grade for each dictionary. max() compares those integers and returns the dictionary with the highest grade. Without a key, Python would try to compare dictionaries directly, which raises a TypeError because dictionaries are not orderable.

min() and max() also accept a key when you need the element that minimizes or maximizes a computed property. For example, finding the point closest to the origin:

python
points = [(1, 2), (3, -1), (0, 4)] closest = min(points, key=lambda p: p[0] ** 2 + p[1] ** 2) print(closest) # (1, 2)

The key function computes the squared distance, and min() returns the tuple with the smallest distance. This pattern is common in geometry, data processing, and anywhere you need to select an item based on a derived value.

Common Key Functions: lambda, itemgetter, attrgetter

A lambda is the most direct way to define a key inline, but it is not always the best choice. For accessing dictionary keys or object attributes, the operator module provides itemgetter and attrgetter, which are often faster and more readable.

python
from operator import itemgetter, attrgetter # itemgetter for dictionaries and sequences people = [{'name': 'Alice', 'age': 30}, {'name': 'Bob', 'age': 25}] sorted_by_age = sorted(people, key=itemgetter('age')) # attrgetter for objects class Person: def __init__(self, name, age): self.name = name self.age = age persons = [Person('Alice', 30), Person('Bob', 25)] sorted_persons = sorted(persons, key=attrgetter('age'))

itemgetter('age') returns a function that fetches the 'age' key from a dictionary. attrgetter('age') returns a function that fetches the age attribute from an object. They can be faster than an equivalent lambda in tight loops and make the intent explicit: you are extracting a specific field.

When you need to combine multiple fields, both itemgetter and attrgetter accept multiple arguments. For example, itemgetter('last', 'first') returns a tuple of two values, which Python compares lexicographically. This is a clean way to implement multi-key sorting without writing a custom function.

Sorting by Multiple Keys

Python's sort is stable, meaning that when two elements have equal keys, their original order is preserved. You can exploit this to sort by multiple criteria by chaining sorts, or you can use a key that returns a tuple. The tuple approach is usually simpler and avoids multiple passes.

python
records = [ {'name': 'Alice', 'age': 30, 'score': 88}, {'name': 'Bob', 'age': 25, 'score': 92}, {'name': 'Charlie', 'age': 30, 'score': 75}, ] # Sort by age, then by score descending sorted_records = sorted(records, key=lambda r: (r['age'], -r['score']))

The key returns a tuple (age, -score). Python compares the first elements, and only if they are equal does it compare the second. Using the negative score reverses the order for that field. This is a common trick when you want descending order for one key and ascending for another.

If you need different directions for each key, the tuple approach works as long as the values are numeric. For strings, you cannot simply negate them. In that case, you can use the reverse parameter only for the entire sort, or you can sort twice with different keys, relying on stability. The two-pass method is often clearer:

python
# Sort by name ascending, then by age descending records.sort(key=lambda r: r['age'], reverse=True) records.sort(key=lambda r: r['name'])

The second sort is the primary key; the first sort becomes the secondary key because stability keeps the relative order from the first sort when names are equal. This pattern is worth knowing because it works for any data type, not just numbers.

Performance and Memory Considerations

The key function is called once per element, which is efficient. However, the keys themselves are stored in memory during the sort. For a large list, this means Python allocates a temporary list of keys alongside the original list. The memory overhead is O(n), which is usually acceptable but worth knowing when sorting millions of items.

Choosing a fast key function matters. A lambda that performs attribute access is generally slower than attrgetter, so prefer itemgetter and attrgetter over lambdas when sorting a large dataset in a hot path. If you need to compute a complex key that involves multiple operations, a lambda may be unavoidable. If the key computation is expensive, precompute the keys and sort indices instead.

Another subtle point: the key function should be deterministic and free of side effects. Python calls it exactly once per element, but if the key function mutates the element or relies on external state, the result may be unpredictable. Keep the key function pure: it should take an element and return a value without modifying anything.

Edge Cases and Common Pitfalls

A key function that returns None causes a TypeError, because None does not define an ordering. This is easy to trigger by forgetting a return in the key function. For example, sorted(data, key=lambda x: x.method()) fails if method() returns None for any element. Always ensure the key function returns a comparable value.

Using a key that returns a list is allowed: lists compare lexicographically, just like tuples. The comparison can still raise a TypeError if the lists contain incompatible types. If you need the key to be hashable for later use in a set or dictionary, convert the list to a tuple first; for sorting alone, either works and a tuple is often clearer.

When working with mixed-type data, the key function can normalize types. For instance, sorting a list that contains both int and str values directly raises a TypeError. A key function like lambda x: (type(x).__name__, str(x)) can force a consistent ordering, but this is rarely what you want. Better to clean the data upstream than to rely on a contrived key.

Finally, remember that the key function is evaluated once per element. If it reads mutable external state, the order produced can be surprising because the key values are captured before sorting begins. Keep the key function independent of state that can change during the operation.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.