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.
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.
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.
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.
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.
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__.
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.
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:
- Call
super().__new__(cls)unless you deliberately block allocation. - Use
__new__only when allocation itself needs customizing; prefer__init__otherwise. - Set values needed by an immutable type in
__new__, before the object is returned. - Remember that
__init__is skipped when the returned object is not an instance ofcls. - Keep singleton initialization idempotent, since
__init__may run more than once.
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
List all Python tutorials.