ZetCode

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.

basic_iadd.py
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.

shared_iadd.py
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.

fallback_add.py
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.

notimplemented_iadd.py
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.

operator_iadd.py
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.

list_tuple_iadd.py
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.

inherited_iadd.py
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.

type_lookup.py
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.

money_iadd.py
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:

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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Python tutorials.