Python __iadd__ Method
Last modified November 18, 2026 Python 3.15
The += operator calls __iadd__ on its left operand.
Unlike __add__, the method is expected to update that object in
place and return it. This article shows the dispatch, the fallback to
__add__ when the hook is missing or declines, why shared
references see an in-place change, and how to write the hook for your own
classes.
The += dispatch
a += b is evaluated as
a = type(a).__iadd__(a, b). The hook is looked up on the type,
receives both operands, and its return value is bound back to the name on the
left. The trace below makes the two calls visible.
class Total:
def __init__(self, value):
self.value = value
def __iadd__(self, other):
print("__iadd__", self.value, "+", other)
self.value += other
return self
def __repr__(self):
return f"Total({self.value})"
t = Total(10)
t += 5
t += 3
print(t)
Each += calls the method once. The method changes
self.value and returns self, so the name
t is rebound to the same object. Returning something else — even
by accident — would silently replace the original object.
$ python basic_iadd.py __iadd__ 10 + 5 __iadd__ 15 + 3 Total(18)
In-place means shared references see the change
Because a well-behaved __iadd__ mutates the existing object,
every name pointing at it observes the new state. The is test
below confirms that no new object was created.
class Box:
def __init__(self, value):
self.value = value
def __iadd__(self, other):
self.value += other
return self
def __repr__(self):
return f"Box({self.value})"
b = Box(1)
alias = b
b += 4
print(b, alias, b is alias)
Both names print Box(5) and b is alias is
True. This is the semantic difference from b = b + 4,
which would leave alias pointing at the old object.
$ python shared_iadd.py Box(5) Box(5) True
Fallback to __add__
When a class has no __iadd__, Python evaluates
a += b as a = a + b: it calls __add__
(and, if needed, the reflected __radd__) and rebinds the name to
the result. Immutable built-ins such as int, str and
tuple follow this path.
class Frozen:
def __init__(self, value):
self.value = value
def __add__(self, other):
print("__add__")
return Frozen(self.value + other)
def __repr__(self):
return f"Frozen({self.value})"
f = Frozen(1)
alias = f
f += 4
print(f, alias, f is alias)
The __add__ call built a new Frozen object, which
was assigned to f. The alias still holds Frozen(1),
and the identity test is False. A class that cannot mutate itself
should normally implement __add__ only.
$ python fallback_add.py __add__ Frozen(5) Frozen(1) False
Returning NotImplemented
An __iadd__ that does not support the right operand returns
NotImplemented rather than raising an error. Python then tries
__add__ on the left operand and the reflected
__radd__ on the right one before giving up.
class Units:
def __init__(self, amount):
self.amount = amount
def __iadd__(self, other):
if not isinstance(other, int):
return NotImplemented
self.amount += other
return self
def __add__(self, other):
print("__add__")
if not isinstance(other, int):
return NotImplemented
return Units(self.amount + other)
def __repr__(self):
return f"Units({self.amount})"
class Addable:
def __radd__(self, other):
print("__radd__ of Addable")
return 42
u = Units(5)
u += 3
print(u)
u += Addable()
print(u)
v = Units(5)
try:
v += "x"
except TypeError as e:
print(type(e).__name__, e)
Adding an int uses __iadd__. Adding an
Addable declines both hooks on Units and reaches
Addable.__radd__, whose result 42 is bound to
u. With a string no method can handle the operation, so Python
raises TypeError. Note that NotImplemented (a
sentinel) is different from NotImplementedError (an exception).
$ python notimplemented_iadd.py Units(8) __add__ __radd__ of Addable 42 __add__ TypeError unsupported operand type(s) for +=: 'Units' and 'str'
The operator.iadd function
The operator module exposes the in-place operators as
functions. operator.iadd(a, b) performs the same hook call as
a += b, but it cannot rebind the caller's variable.
import operator
class Box:
def __init__(self, value):
self.value = value
def __iadd__(self, other):
self.value += other
return self
def __repr__(self):
return f"Box({self.value})"
b = Box(1)
result = operator.iadd(b, 4)
print(b, result, b is result)
xs = [1, 2]
ys = [3]
print(operator.iadd(xs, ys), xs)
For the mutable Box and list the returned object is the one
that was changed. When the operand is immutable, operator.iadd
returns a new object that you must assign yourself — the function does not
write back to b or xs.
$ python operator_iadd.py Box(5) Box(5) True [1, 2, 3] [1, 2, 3]
Lists and tuples
The built-in collections show both strategies side by side. A list
extends itself and keeps its identity; a tuple has no __iadd__,
so += builds a new tuple.
a = [1, 2] alias = a a += [3] print(a, alias, a is alias) t = (1, 2) talias = t t += (3,) print(t, talias, t is talias)
The list's __iadd__ behaves like extend, so the
alias sees the third element. The tuple operation is equivalent to
t = t + (3,). Keep this in mind when another variable or a
container holds a reference to the same list.
$ python list_tuple_iadd.py [1, 2, 3] [1, 2, 3] True (1, 2, 3) (1, 2) False
Inheritance and super()
A subclass can wrap the hook to add behaviour and delegate the actual
state change to the base class with super().__iadd__. It must
still return self.
class Base:
def __init__(self, value):
self.value = value
def __iadd__(self, other):
self.value += other
return self
class Logging(Base):
def __iadd__(self, other):
print(f"adding {other} to {self.value}")
super().__iadd__(other)
return self
def __repr__(self):
return f"Logging({self.value})"
b = Logging(10)
b += 5
print(b)
The subclass prints a message, then the base method updates
value. Dropping the final return self would bind
None to b, which is a common mistake when extending
in-place hooks.
$ python inherited_iadd.py adding 5 to 10 Logging(15)
Special methods are looked up on the type
Like all special methods, __iadd__ is looked up on the
class, not on the instance. A hook assigned to a single object is ignored by
the operator.
class Counter:
def __init__(self, n):
self.n = n
def __iadd__(self, other):
self.n += other
return self
c = Counter(1)
c.__iadd__ = lambda other: print("instance hook called")
c += 2
print(c.n)
The lambda stored on c never runs; the method defined on
Counter changed n to 3. To change the behaviour of
the operator you must change the class (or a base class), not the instance.
$ python type_lookup.py 3
Validating the right operand
An in-place hook is a good place to enforce a domain rule before
changing state. Here a Money object refuses to add an amount in
a different currency.
class Money:
def __init__(self, amount, currency):
self.amount = amount
self.currency = currency
def __iadd__(self, other):
if isinstance(other, Money):
if other.currency != self.currency:
raise ValueError("currency mismatch")
other = other.amount
self.amount += other
return self
def __repr__(self):
return f"Money({self.amount}, {self.currency!r})"
m = Money(10, "EUR")
m += 5
print(m)
m += Money(3, "EUR")
print(m)
try:
m += Money(1, "USD")
except ValueError as e:
print(type(e).__name__, e)
The object accepts a plain number and another Money in the
same currency. The check runs before self.amount is touched, so a
rejected operation leaves the object unchanged.
$ python money_iadd.py Money(15, 'EUR') Money(18, 'EUR') ValueError currency mismatch
Best practices
A few rules keep in-place addition predictable:
- Return
selffor a mutable object; the operator binds the return value to the left-hand name. - Mutate the existing object instead of building a new one when the class is mutable.
- Return
NotImplementedfor unsupported operand types and let Python try the reflected operation. - Implement
__add__as well if the object can be used with+or is immutable. - Validate before changing state so a failed operation leaves the object intact.
Source
object.__iadd__ - Python documentation
Emulating numeric types - Python documentation
operator.iadd - Python documentation
In this article we have implemented the __iadd__ method. We
have covered the += dispatch, the fallback to __add__,
shared references, operator.iadd, and validation. For related
topics, see Python __add__ method,
Python __isub__ method, and
Python __imul__ method.
Author
List all Python tutorials.