Python __iadd__: How += Mutates or Reassigns
Understand Python's __iadd__ method and how += dispatches to it, with the fallback to __add__, return-value rules, and mutable vs immutable differences.

In Python, the += operator is syntactic sugar for a method call. When you write a += b, the interpreter first looks for a.__iadd__(b). The i stands for "in-place," and the method's job is to add b to a and return the result, which is then assigned back to the name a. Understanding Python's __iadd__ is the key to predicting whether an augmented assignment mutates an existing object or silently creates a new one.
What __iadd__ Does and When Python Calls It
The critical detail is that __iadd__ is expected to mutate the receiver and return it. Unlike __add__, which builds a brand-new object, __iadd__ is allowed to change the existing object in place and return self. That is why list.__iadd__ behaves like extend rather than like + on tuples.
class Counter:
def __init__(self, value=0):
self.value = value
def __iadd__(self, other):
self.value += other
return self
c = Counter(5)
c += 3
print(c.value) # 8Here c += 3 calls c.__iadd__(3), which increments the internal value attribute and returns self. The name c still references the same object; only its state changed.
The Fallback Path: When __iadd__ Is Not Defined
If a type does not define __iadd__, or its __iadd__ returns NotImplemented, Python falls back to the regular addition path. The expression a += b is then evaluated as a = a.__add__(b), or a = b.__radd__(a) when a.__add__ is missing or returns NotImplemented.
This fallback is not a subtle edge case; it is the normal behavior for immutable types. Integers, strings, and tuples do not implement __iadd__ because they cannot be mutated. When you write:
x = 10
x += 5Python evaluates x = x.__add__(5) and rebinds x to the result, leaving the original integer unchanged. If no other references remain, the original object can be garbage-collected.
The same fallback applies to user-defined classes that only implement __add__. If you forget to define __iadd__, += still works, but it produces a new object instead of mutating the existing one. That difference matters when the object is referenced from multiple places.
Mutable vs. Immutable Behavior: Why Lists and Tuples Differ
The distinction between __iadd__ and the fallback to __add__ is easiest to see by comparing lists and tuples.
items = [1, 2]
original = items
items += [3]
print(items) # [1, 2, 3]
print(original) # [1, 2, 3] -- same objectBecause list defines __iadd__, the operation mutates the existing list. The variable original still points to the same list object, so it sees the change.
t = (1, 2)
original = t
t += (3,)
print(t) # (1, 2, 3)
print(original) # (1, 2) -- new objectTuples have no __iadd__, so += falls back to __add__ and creates a new tuple. The name t is rebound, but original still references the old tuple. This is why aliasing bugs appear with mutable types: any code holding a reference to the list observes the mutation, while code holding a reference to the tuple does not.
Implementing __iadd__ on a Custom Class
When designing a mutable container or accumulator, implementing __iadd__ gives callers the same in-place semantics they expect from built-in lists. A common pattern is a class that aggregates items:
class Bundle:
def __init__(self, items=None):
self.items = list(items) if items else []
def __iadd__(self, other):
self.items.extend(other)
return self
def __add__(self, other):
result = Bundle(self.items)
result.items.extend(other)
return resultWith both methods defined, bundle += extra mutates the existing bundle, while bundle + extra returns a new bundle and leaves the original untouched. This matches the behavior of list and gives users a predictable API.
Note that __iadd__ and __add__ do not have to share an implementation. __iadd__ can be more efficient because it avoids copying the existing contents. In the example above, __add__ copies the list, while __iadd__ does not.
The return self Requirement and What Breaks Without It
The most common bug when implementing __iadd__ is forgetting to return anything. The augmented assignment a += b always assigns the return value of the method back to the left-hand name. If __iadd__ returns None, the name becomes None.
class BrokenCounter:
def __init__(self, value=0):
self.value = value
def __iadd__(self, other):
self.value += other
# missing: return self
c = BrokenCounter(5)
c += 3
print(c) # NoneThe mutation did happen; the internal value was incremented. But because the method returned None, the assignment c = c.__iadd__(3) rebinds c to None, and the original object is lost. This is a silent failure that often surfaces later as an AttributeError or a confusing None value in a data structure.
The same rule applies to __imul__, __isub__, and the other in-place operators. They must all return the object that should be bound to the left-hand name, which is normally self.
Memory and Allocation Implications of In-Place Addition
The practical reason to implement __iadd__ is to avoid allocating a new object on every operation. For a loop that accumulates values, the difference can be significant.
def accumulate_with_plus(n):
total = []
for i in range(n):
total = total + [i] # new list each iteration
return total
def accumulate_with_iadd(n):
total = []
for i in range(n):
total += [i] # extends in place
return totalThe first version creates a new list on every iteration and copies all previous elements into it, giving O(n²) copying work overall. The second version calls list.__iadd__, which extends the existing list in place and typically amortizes to O(n) total work. The exact allocation behavior depends on the list's internal capacity growth, but the structural difference is clear: one path copies the entire prefix each time, and the other does not.
For immutable types there is no choice; += must allocate because the original cannot change. For custom mutable classes, implementing __iadd__ is the way to give users the efficient path.
Interaction with __add__ and __radd__ in Subclasses
When a class inherits __iadd__ from a parent, subclass instances use the parent's implementation unless the subclass overrides it. A subtle issue arises when a subclass adds state that the inherited __iadd__ should preserve.
class BaseList(Bundle):
pass
class TaggedList(BaseList):
def __init__(self, items=None, tag=""):
super().__init__(items)
self.tag = tagHere TaggedList inherits __iadd__ from Bundle. Since Bundle.__iadd__ returns self, the tag attribute is preserved, and the operation mutates the existing instance. If the parent's __iadd__ had instead returned a new object of the parent type, the subclass's extra attributes would be lost. This is why returning self rather than constructing a new instance is not just a convention; it preserves the dynamic type and all subclass state.
For augmented assignment, __radd__ is only relevant when the left operand's __add__ is missing or returns NotImplemented. For a += b, Python tries a.__iadd__(b) first, then a.__add__(b), then b.__radd__(a), with each step applying only if the previous method is missing or returns NotImplemented. In practice, __radd__ matters more for + expressions where the left operand is a built-in type, such as int + MyClass. For +=, the left operand is usually the object being mutated, so __radd__ rarely comes into play.
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.