Customizing Python Dataclass Repr Output
Learn how Python dataclass repr works, how to exclude fields, write a custom __repr__, and weigh performance and logging tradeoffs.

When you define a Python dataclass, the generated __repr__ method gives you a readable string representation of the instance. This is useful for debugging and logging, but the default behavior may not always match your needs. Understanding how the dataclass repr is generated lets you control exactly what appears in logs and error messages without writing verbose boilerplate.
The default repr is generated automatically when you use the @dataclass decorator. For example:
from dataclasses import dataclass
@dataclass
class Point:
x: float
y: float
label: str = "origin"
p = Point(1.0, 2.0, "target")
print(p)This prints Point(x=1.0, y=2.0, label='target'). The repr includes every field in the order they are declared, using the field name and its repr() output. For most simple classes this is exactly what you want. But there are cases where the default repr is too noisy, exposes sensitive data, or simply doesn't convey the right information.
Controlling Repr with the repr Parameter in @dataclass
The @dataclass decorator accepts a repr parameter. Setting repr=False stops the decorator from adding a generated __repr__ method. This is useful when you want to define your own repr or rely on object.__repr__ for a minimal representation. If you define __repr__ in the class body, the decorator does not overwrite it, so repr=False is redundant in that case.
from dataclasses import dataclass
@dataclass(repr=False)
class User:
username: str
email: str
password_hash: str
user = User("alice", "alice@example.com", "abc123")
print(user) # <__main__.User object at 0x...>With repr=False and no custom method, the class uses object.__repr__, which shows only the class name and memory address. That is rarely useful for debugging. If you need a readable output, define your own __repr__ method as shown later.
Excluding Fields from Repr with field(repr=False)
A more common need is to exclude specific fields from the repr while keeping the auto-generated method. The field() function accepts a repr argument. Setting repr=False on a field omits it from the repr output.
from dataclasses import dataclass, field
@dataclass
class Credentials:
username: str
password: str = field(repr=False)
api_key: str = field(repr=False, default="")
c = Credentials("admin", "s3cret", "key123")
print(c) # Credentials(username='admin')Here the password and api_key are excluded, so the repr does not leak sensitive information in logs. This is a simple and effective way to keep the automatic repr while redacting fields. The excluded fields still participate in equality, so you don't lose functionality.
You can also use field(repr=False) on fields that are expensive to format. For example, a large binary blob or a complex nested object might make the repr slow to compute. Excluding it keeps repr calls cheap.
Customizing Repr Output with a Custom __repr__
When the auto-generated repr is not flexible enough, you can override __repr__ manually. This is often done when you want a more compact representation, include computed properties, or format fields differently.
from dataclasses import dataclass
@dataclass
class Temperature:
celsius: float
def __repr__(self):
return f"Temperature({self.celsius:.1f}°C)"
print(Temperature(23.456)) # Temperature(23.5°C)Note that when you define __repr__ explicitly, the dataclass decorator does not override it. The repr parameter in @dataclass is ignored for classes that already define __repr__. This is a common source of confusion: if you set repr=False but also define a custom __repr__, your custom method is used. The repr parameter only controls whether the decorator generates one.
A custom repr gives you full control over the string format. You can include only the fields that matter, add context, or even hide the class name entirely. However, you lose the automatic consistency that the generated repr provides. If you add or remove fields later, you must update the custom repr manually.
Repr and Performance: When Customization Matters
Calling repr() on a dataclass instance is not free. The generated repr iterates over all fields and calls repr() on each value. For most objects this is negligible, but it can become a bottleneck in hot paths where repr is called frequently, such as in logging within a loop or in exception messages.
Excluding fields with field(repr=False) reduces the number of values that need to be formatted. If a field has an expensive __repr__ (e.g., a large list or a custom object that does heavy computation), omitting it can significantly speed up repr calls. However, the main cost is usually the conversion to string, not the iteration itself. If you need to log thousands of objects per second, consider using a more efficient logging format like JSON or a structured logger instead of relying on repr.
Another performance aspect is the use of repr in f-strings. When you embed a dataclass instance in an f-string and the class has no custom __str__, Python falls back to __repr__. If the repr is expensive, that cost is paid every time the f-string is evaluated. You can force repr explicitly with {obj!r} or keep heavy fields out of the repr. Measure first; premature optimization is rarely worth the complexity.
Repr, Debugging, and Logging: Practical Considerations
A good repr is a debugging tool. It should give you enough information to identify the object state without dumping everything. The default repr is often sufficient, but there are scenarios where you want to tailor it.
For logging, you might want to include a correlation ID or a timestamp that is not part of the dataclass fields. You can add those as properties and include them in a custom repr:
from dataclasses import dataclass, field
from time import time
@dataclass
class Request:
method: str
path: str
_created: float = field(default_factory=time, repr=False)
@property
def age_ms(self):
return (time() - self._created) * 1000
def __repr__(self):
return f"Request(method={self.method!r}, path={self.path!r}, age_ms={self.age_ms:.1f})"Here the raw timestamp is excluded, but the computed age appears in the repr. This keeps the repr informative without exposing internal implementation details.
When using dataclasses in a larger system, consistency in repr format helps when grepping logs. If all your dataclasses follow the same pattern, you can quickly scan output. But don't over-engineer; the default format is already consistent across your codebase.
Common Pitfalls and Edge Cases
One pitfall is relying on repr=False to hide sensitive fields but forgetting that the field still participates in equality. Excluding a field from repr does not exclude it from comparison. If two objects have different passwords but the same username, they are considered unequal, which might be intended. If a field is used in equality but you do not want it in logs, consider using field(compare=False, repr=False) as well. For hashable dataclasses, the same field also affects the generated __hash__ unless compare=False.
Another edge case is inheritance. When a dataclass inherits from another dataclass, the generated repr includes fields from the base class first, then the subclass fields. If you override __repr__ in the subclass, you must handle base class fields manually. For example:
from dataclasses import dataclass
@dataclass
class Base:
id: int
@dataclass
class Derived(Base):
name: str
def __repr__(self):
return f"Derived(id={self.id}, name={self.name!r})"If you forget to include id, the repr omits a field that is part of the object's state. This is a maintainability concern when the base class changes.
Finally, note that the repr parameter in @dataclass only affects the generated method. If you define __repr__ in the class body, the decorator respects it. In other words, setting repr=False does not disable a manually written __repr__; it only prevents the decorator from generating one. Knowing this distinction helps you avoid confusion when mixing custom methods with dataclass options.
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.