ZetCode

Python __new__ Method

Last modified November 18, 2026 Python 3.15

Python creates an instance in two steps: __new__ allocates and returns the object, then __init__ initializes it. Normally you only write __init__, but __new__ is needed when you must control allocation itself. This article covers the call order, immutable subclasses, read-only properties, singletons, instance limits, metaclasses and returning an object of a different class.

The object creation lifecycle

Calling a class invokes __new__ first and then, if the returned object is an instance of the class, __init__. The hooks print their names so the order is visible.

lifecycle.py
class Example:
    def __new__(cls, *args, **kwargs):
        print("__new__ called")
        instance = super().__new__(cls)
        return instance

    def __init__(self, value):
        print("__init__ called")
        self.value = value


obj = Example(42)
print(obj.value)

Allocation happens before initialization. The call to super().__new__(cls) delegates to object.__new__, which does the actual allocation; skipping it would leave you without a real instance.

$ python lifecycle.py
__new__ called
__init__ called
42

Subclassing an immutable type

Built-in immutable types such as int cannot be changed after creation, so their value must be set in __new__. This subclass stores the absolute value of its argument.

immutable_int.py
class AbsoluteInt(int):
    def __new__(cls, value):
        return super().__new__(cls, abs(value))


n = AbsoluteInt(-7)
print(n)
print(type(n).__name__)
print(n + 1)

The value is fixed at creation time, and the new instance behaves like an integer. Arithmetic produces a plain int here unless the subclass also overrides those operations — type(n).__name__ only reports the type of the original object.

$ python immutable_int.py
7
AbsoluteInt
8

Read-only properties

A class can set attributes in __new__ and expose them through properties without setters. Assigning to the property then raises AttributeError.

readonly.py
class ImmutablePoint:
    def __new__(cls, x, y):
        instance = super().__new__(cls)
        instance._x = x
        instance._y = y
        return instance

    @property
    def x(self):
        return self._x

    @property
    def y(self):
        return self._y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"


point = ImmutablePoint(3, 4)
print(point)
try:
    point.x = 5
except AttributeError as e:
    print(type(e).__name__, e)

The public properties are read-only. This is a convention rather than true immutability: point._x = 5 would still work. Use an immutable base type or guard __setattr__ when the value must really be frozen.

$ python readonly.py
Point(3, 4)
AttributeError property 'x' of 'ImmutablePoint' object has no setter

The singleton pattern

A singleton class keeps one instance in a class attribute and returns it from __new__ on every call. Be aware that __init__ still runs each time unless you add a guard.

singleton.py
class Singleton:
    _instance = None

    def __new__(cls):
        if cls._instance is None:
            print("creating instance")
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self):
        print("initializing")


s1 = Singleton()
s2 = Singleton()
print(s1 is s2)

Only one object was created, but the initial message printed twice. To avoid reinitialization, set a flag on the instance in __init__ and return early when it is already present.

$ python singleton.py
creating instance
initializing
initializing
True

Limiting the number of instances

Because __new__ sees every construction request, it can refuse to allocate after a limit is reached. A deterministic counter is clearer than relying on __del__ and garbage collection.

limited.py
class Limited:
    MAX = 2
    _created = 0

    def __new__(cls):
        if cls._created >= cls.MAX:
            raise RuntimeError("instance limit reached")
        cls._created += 1
        return super().__new__(cls)


objs = [Limited() for _ in range(2)]
print("created:", Limited._created)
try:
    Limited()
except RuntimeError as e:
    print(type(e).__name__, e)

Two instances were allowed, and the third request raised a clear error. Since the count is incremented in __new__, it is exact and does not depend on when objects are collected.

$ python limited.py
created: 2
RuntimeError instance limit reached

A metaclass __new__

A metaclass's __new__ controls class creation instead of instance creation. It receives the class name, its bases and the namespace dictionary, which it may modify before calling super().__new__.

metaclass_new.py
class Meta(type):
    def __new__(mcls, name, bases, namespace):
        namespace["version"] = 1.0
        return super().__new__(mcls, name, bases, namespace)


class Widget(metaclass=Meta):
    pass


print(Widget.version)
Widget.version = 2.0
print(Widget.version)

The metaclass injected a version attribute into every class it creates. Normal class code can still reassign it afterwards, because the injection happens once at definition time.

$ python metaclass_new.py
1.0
2.0

Returning a different type

If __new__ returns an object that is not an instance of the class, Python skips __init__ entirely. This makes it possible to use a class as a factory for another type.

factory_new.py
class Result:
    def __init__(self, value):
        print("Result.__init__")
        self.value = value

    def __repr__(self):
        return f"Result({self.value})"


class Factory:
    def __new__(cls, value):
        print("Factory.__new__")
        return Result(value)

    def __init__(self, value):
        print("Factory.__init__")   # never runs


obj = Factory(10)
print(type(obj).__name__, obj)

Only the factory's __new__ and the result's __init__ ran. A related pattern is a flyweight: cache instances by value in __new__ so equal requests share one object.

$ python factory_new.py
Factory.__new__
Result.__init__
Result Result(10)

Best practices

A few rules keep __new__ predictable:

Source

object.__new__ - Python documentation

Basic customization - Python documentation

Metaclasses - Python documentation

PEP 237 - Unifying Long Integers and Integers

In this article we have implemented the __new__ method. We have covered the creation lifecycle, immutable subclasses, read-only properties, singletons, instance limits, metaclasses and factory behaviour. For related topics, see Python __init__ method, Python metaclasses, and Python object-oriented programming.

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.