Python Dataclass Order: Sorting with order=True
Learn how order=True in Python dataclasses generates comparison methods, sorts instances, and customizes field ordering.

The dataclass ordering feature in Python, enabled by passing order=True to the @dataclass decorator, generates comparison methods (__lt__, __le__, __gt__, __ge__) based on the class fields in the order they are declared. This lets you sort and compare instances without manually writing boilerplate comparison logic.
What order=True Generates in a Dataclass
When you define a dataclass with order=True, Python automatically adds the four rich comparison methods. These methods compare instances by treating the fields as a tuple in the order they are defined. For example:
from dataclasses import dataclass
@dataclass(order=True)
class Product:
name: str
price: floatWith this definition, Product instances can be compared using <, <=, >, >=. The generated __lt__ method is roughly equivalent to:
def __lt__(self, other):
return (self.name, self.price) < (other.name, other.price)This tuple comparison is efficient and follows Python's standard lexicographic ordering. It also means that if a comparison reaches a field whose values are not mutually comparable, it will raise a TypeError at comparison time.
How Field Order Determines Comparison Behavior
The order of fields in the dataclass definition is significant. Comparison proceeds field by field, from first to last. The first field that differs determines the result. If two instances have identical values for all fields, they are considered equal (assuming eq=True, which is the default).
Consider this example:
@dataclass(order=True)
class Person:
age: int
name: strHere, age is compared before name. So Person(30, "Alice") is not less than Person(25, "Bob") because 30 is greater than 25, regardless of the names. In other words, Person(25, "Bob") < Person(30, "Alice") evaluates to True. If you need to sort by name first, you must reorder the fields or use a custom sort key.
This behavior is a common source of subtle bugs. Changing the order of fields in the class body silently changes the comparison semantics. It's a maintainability concern that you should keep in mind when using order=True.
Sorting Dataclass Instances with sorted() and list.sort()
Once a dataclass has order=True, instances become sortable using Python's built-in sorting functions. For example:
products = [
Product("Laptop", 999.99),
Product("Mouse", 19.99),
Product("Keyboard", 49.99),
]
sorted_products = sorted(products)The sorted() function uses the generated __lt__ method to determine order. The same applies to list.sort():
products.sort()This works without any additional key function. However, if you need a different ordering than the natural field order, you can still pass a key function to sorted() or list.sort(). For instance, to sort by price descending:
products.sort(key=lambda p: p.price, reverse=True)Using a key function bypasses the generated comparison methods entirely, which can be useful when you need a one-off ordering.
Excluding Fields from Comparison with field(compare=False)
Sometimes you want to include a field in the dataclass but exclude it from the generated comparison methods. The field() function accepts a compare parameter. Setting compare=False omits that field from the tuple used in comparisons.
from dataclasses import dataclass, field
@dataclass(order=True)
class User:
id: int
username: str
created_at: float = field(compare=False)In this example, created_at is not considered when comparing User instances. This is useful for fields that are metadata or derived values that shouldn't affect ordering. It also prevents TypeError if that field is not comparable.
Note that compare=False does not affect equality; it only removes the field from the ordering tuple. Equality still uses all fields unless you also set eq=False or use field(eq=False).
Custom Ordering When order=True Is Not Enough
The generated comparison methods are based on the declared field order. If your ordering logic is more complex—for example, comparing by a computed property or using a non-standard rule—you can override the comparison methods manually.
One approach is to implement __lt__ yourself and leave order=False (the default). This gives you full control:
from dataclasses import dataclass
from datetime import datetime
@dataclass
class Task:
priority: int
due_date: datetime
def __lt__(self, other):
if self.priority != other.priority:
return self.priority < other.priority
return self.due_date < other.due_dateYou can also use order=True and then override one or more methods. However, mixing generated and manual methods can be confusing. A cleaner alternative is to use a key function at the call site, which keeps the dataclass simple and the ordering logic local to the sort operation.
For example, if you need to sort by a field that isn't first, a key function is often more readable than reordering fields or overriding methods:
sorted_tasks = sorted(tasks, key=lambda t: (t.due_date, t.priority))Choose the approach that best matches the maintainability needs of your codebase.
Performance and Maintainability of Generated Comparison Methods
The generated comparison methods are simple tuple comparisons, so they follow the same lexicographic ordering rules as ordinary tuple comparisons and are efficient for typical use. The overhead is minimal because the tuple construction happens only during comparison, not at instance creation.
From a maintainability perspective, order=True reduces boilerplate and ensures consistency. You don't have to write and test multiple comparison methods. However, the implicit dependency on field order can be fragile. If a colleague reorders fields for clarity, the sorting behavior changes silently. To mitigate this, you can:
- Keep field order stable and document it.
- Use
field(compare=False)to explicitly exclude fields that shouldn't affect ordering. - Write unit tests that verify sorting behavior.
Another consideration is that order=True generates all four comparison methods even when you only use one. This is usually harmless; the real cost is in code clarity, not runtime performance.
If you prefer explicit control and only need < for sorting, you can implement just __lt__ manually. In most applications, the convenience of order=True outweighs the extra code this requires.
In summary, order=True is a useful feature for Python dataclasses that simplifies sorting and comparison. Understanding how it uses field order, how to exclude fields, and when to override it gives you precise control over your data model's behavior.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.