Python __new__ Metaclass: Class Creation Explained
Understand how __new__ in a metaclass controls class creation, how it differs from __init__, and when to use it for class customization.

The __new__ method in a metaclass is a common source of confusion because it operates at a different stage from __new__ in a regular class. When you define a metaclass, you can override __new__ to intercept the creation of the class object itself. The class body has already executed by this point, so __new__ receives the resulting namespace and can modify the class's attributes, methods, or even its bases before the class object is returned.
What __new__ Does in a Metaclass
In a metaclass, __new__ is responsible for creating the class object. The signature is:
class Meta(type):
def __new__(mcls, name, bases, namespace, **kwargs):
cls = super().__new__(mcls, name, bases, namespace)
return clsHere mcls is the metaclass itself, name is the class name, bases is a tuple of base classes, and namespace is the mapping returned by __prepare__ (usually a dict) containing the class body's contents. The **kwargs are extra keyword arguments passed in the class definition, such as some_option=True in class MyClass(metaclass=Meta, some_option=True). The metaclass keyword itself is consumed by the class-creation machinery and does not appear in **kwargs.
__new__ returns the newly created class object. If you don't override it, type.__new__ does the work. When you override it, you can inspect or modify the namespace before passing it to super().__new__(), or you can even return a completely different object.
How Class Creation Works with __new__ and __init__
When Python executes a class definition, it follows a specific order:
- The metaclass's
__prepare__method creates the namespace (by default, an empty dict). - The class body is executed, populating the namespace.
- The metaclass's
__new__is called to create the class object. - The metaclass's
__init__is called to initialize the class object, if__new__returns an instance of the metaclass.
This means __new__ runs before __init__. If __new__ does not return an instance of the metaclass, __init__ is not called. This separation is useful when you need to construct the class object itself, rather than just configure it after creation.
A Minimal Metaclass Using __new__
Here's a minimal example that adds a class attribute automatically:
class AutoAttributeMeta(type):
def __new__(mcls, name, bases, namespace, **kwargs):
namespace.setdefault('created_by', 'AutoAttributeMeta')
return super().__new__(mcls, name, bases, namespace)
class MyClass(metaclass=AutoAttributeMeta):
pass
print(MyClass.created_by) # AutoAttributeMetaIn this example, __new__ modifies the namespace mapping before the class object is created. The setdefault call ensures the attribute is only added if it doesn't already exist. This is a clean way to inject defaults without touching the class body.
Using __new__ to Modify the Class Before Creation
Because __new__ receives the namespace as a mutable mapping, you can perform more complex transformations. For example, you might want to wrap all methods with a decorator, or enforce naming conventions:
class UpperMethodMeta(type):
def __new__(mcls, name, bases, namespace, **kwargs):
for key, value in list(namespace.items()):
if callable(value) and not key.startswith('__'):
namespace[key] = lambda *args, _f=value, **kw: _f(*args, **kw) * 2
return super().__new__(mcls, name, bases, namespace)
class Math(metaclass=UpperMethodMeta):
def double(self, x):
return x * 2
m = Math()
print(m.double(3)) # 12, because the method is wrappedThis is a contrived example, but it shows that __new__ can alter the class's methods before the class object exists. The key is that you are working with the raw namespace mapping, so any changes you make are reflected in the final class.
Common Mistakes and Pitfalls
One common mistake is forgetting to call super().__new__() and returning a non-class object. If you return a plain object, Python will not create a class, and __init__ will not run. This can lead to confusing errors.
Another pitfall is relying on __new__ to modify the class after it has been created. If you need to set attributes that depend on the class object itself, use __init__ instead. For example, computing a class-level property that references the class is better done in __init__ because the class already exists there.
Also, be careful with extra keyword arguments in the class definition. If you pass them through to type.__new__, it raises a TypeError because it does not accept arbitrary **kwargs. Handle them explicitly in __new__ or __init__ instead.
When to Use __new__ Instead of __init__ in a Metaclass
Use __new__ when you need to:
- Modify the
namespacebefore the class object is constructed. - Change the bases before calling
super().__new__(). - Return an object that is not an instance of the metaclass (rare).
Use __init__ when you need to configure the class after it exists, such as setting attributes that depend on the class object or validating the class's structure.
In practice, most metaclass customization can be done in __init__, but __new__ is essential when you need to alter the class body before it is turned into a class. For example, a metaclass that automatically registers subclasses might use __init__ to add the class to a registry, while a metaclass that rewrites method signatures would need __new__.
Compatibility and Maintainability Considerations
Metaclasses are a powerful metaprogramming tool, but they add complexity. Overriding __new__ in a metaclass makes the code harder to follow because the class creation flow is no longer standard. Future maintainers must understand the metaclass to reason about the class's behavior.
Performance is rarely a concern because metaclass __new__ runs only once per class definition, not per instance. However, if your metaclass performs heavy processing in __new__, it can slow down module import time. Keep the logic minimal and avoid side effects that depend on external state.
Compatibility across Python versions is generally stable, but test your metaclass with the Python versions you support, especially when the class body uses newer syntax such as annotations.
A final practical note: if you find yourself using __new__ in a metaclass, consider whether a class decorator or a simpler factory function would achieve the same result with less magic. Metaclasses are appropriate when you need to apply behavior across many unrelated classes, but for a single class, a decorator is often clearer.
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.