Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python __init__ Metaclass: How It Works

Understand how __init__ in a Python metaclass runs at class creation time, how it differs from instance __init__, and when to use it.

~6 min readPython
#metaclass#__init__#class creation#Python internals
A diagram showing a metaclass __init__ running at class creation time, with a class object being initialized before instances are created.

When you define a metaclass with an __init__ method, that method runs at class creation time, not when instances of the class are created. This is a common source of confusion for developers coming from regular class design. A metaclass __init__ gives you a hook to customize the class object itself, right after it is constructed.

What __init__ Does in a Metaclass

A metaclass is a class whose instances are classes. When you create a class with class MyClass(metaclass=Meta), Python calls the metaclass to create the class object. The metaclass's __new__ method creates the class, and its __init__ method initializes it. The __init__ receives the newly created class as its first argument, conventionally named cls, along with the class name, bases, and namespace dictionary.

python
class Meta(type): def __init__(cls, name, bases, dct): super().__init__(name, bases, dct) print(f"Metaclass __init__ called for {name}") class MyClass(metaclass=Meta): pass

Running this code prints Metaclass __init__ called for MyClass immediately after the class definition, not when you create an instance of MyClass. This is the core behavior: __init__ in a metaclass is a class-level initializer, not an instance-level one.

The super().__init__(name, bases, dct) call keeps the initialization chain explicit. If your metaclass inherits from another custom metaclass, this call runs that parent's __init__; if the parent is type, it is conventional and harmless. Include it when you override __init__.

How Metaclass __init__ Differs from Class __init__

A regular class's __init__ initializes instances. It runs each time you call MyClass(), receives the instance as self, and sets up instance attributes. A metaclass's __init__ initializes the class itself. It runs exactly once per class definition, receives the class as cls, and can modify class-level attributes, register the class, or validate its structure.

AspectClass __init__Metaclass __init__
Called whenInstance creationClass definition
First argumentself (instance)cls (class)
FrequencyEvery instantiationOnce per class definition
PurposeInitialize instance stateInitialize class state

This distinction is fundamental. If you need to run code when a class is defined, a metaclass __init__ is one way to do it. If you need to run code when an instance is created, use a regular __init__.

Minimal Metaclass Example with __init__

Here is a practical example that adds a class-level attribute automatically and validates the presence of a required method.

python
class ValidatedMeta(type): def __init__(cls, name, bases, dct): super().__init__(name, bases, dct) if 'required_method' not in dct: raise TypeError(f"{name} must define required_method") cls.created_at = 'class_definition' class GoodClass(metaclass=ValidatedMeta): def required_method(self): pass class BadClass(metaclass=ValidatedMeta): pass # Raises TypeError

In this example, GoodClass is created successfully and gets a created_at attribute. BadClass raises a TypeError at definition time because it lacks the required method. This shows how metaclass __init__ can enforce design contracts early, catching errors before any instance is created.

Order of __new__ and __init__ in Metaclass Creation

When a class is created, the metaclass's __new__ runs first, then its __init__. The __new__ method is responsible for actually creating the class object. It receives the same arguments as __init__ but returns the class object. The __init__ then receives that returned object as cls and initializes it.

python
class TraceMeta(type): def __new__(mcls, name, bases, dct): print(f"__new__ called for {name}") return super().__new__(mcls, name, bases, dct) def __init__(cls, name, bases, dct): print(f"__init__ called for {name}") super().__init__(name, bases, dct) class Demo(metaclass=TraceMeta): pass

Output:

code
__new__ called for Demo __init__ called for Demo

Because __new__ creates the class, it is the place to modify the class dictionary before the class exists. __init__ is better for post-creation setup, such as registering the class or adding attributes that depend on the fully formed class object. If you need to change the class's bases or namespace before creation, override __new__; if you only need to act after creation, __init__ is sufficient and often simpler.

Practical Use Cases for Metaclass __init__

Metaclass __init__ is useful when you need to run code once per class definition. Common scenarios include:

  • Automatic registration: Maintain a registry of all subclasses of a base class.
  • Adding class attributes: Inject helper methods or constants into every class that uses the metaclass.
  • Validating class definitions: Enforce that certain methods or attributes exist, as shown above.
  • Customizing class behavior: Monkey-patch methods or wrap them with additional logic.

For automatic registration, a metaclass __init__ can add each new class to a list or dictionary without requiring explicit registration calls:

python
class RegistryMeta(type): registry = [] def __init__(cls, name, bases, dct): super().__init__(name, bases, dct) if not bases: # Skip the base class itself return RegistryMeta.registry.append(cls) class Base(metaclass=RegistryMeta): pass class ChildA(Base): pass class ChildB(Base): pass print(RegistryMeta.registry) # [<class 'ChildA'>, <class 'ChildB'>]

This pattern is often used in plugin systems or ORMs to automatically discover subclasses. The metaclass __init__ runs at class definition time, so the registry is populated as soon as the module is imported.

Common Mistakes and Pitfalls

One common mistake is forgetting to call super().__init__ in the metaclass __init__ when your metaclass extends another metaclass that does initialization. Without it, that parent initialization is skipped. If the parent is type, the call is conventional rather than strictly required, but including it keeps the chain explicit and helps when metaclasses are composed. Call super().__init__(name, bases, dct) before adding your own logic.

Another pitfall is confusing __init__ with __new__ and trying to modify the class dictionary inside __init__. The dictionary is already used to create the class; changes to it after creation do not affect the class structure. If you need to add or remove methods or attributes before the class exists, do that in __new__.

Metaclass __init__ also runs for every class that uses the metaclass, including base classes. If you do not want the metaclass logic to apply to a base class, check bases or use a flag to skip it, as shown in the registration example.

Finally, avoid doing heavy work inside metaclass __init__. Because it runs at import time, expensive operations can slow down module loading. Keep the logic minimal and defer complex computations to instance methods or class methods when possible.

Performance and Maintainability Considerations

Metaclass __init__ adds a small overhead at class definition time. For most applications, this is negligible, but if you define thousands of classes dynamically, the cumulative cost can become noticeable. The overhead comes from the extra function call and any work you perform inside the method.

Maintainability is a more significant concern. Metaclasses are a powerful but often overused feature. They make class creation implicit, which can confuse developers who are not familiar with the pattern. Before reaching for a metaclass, consider whether a simpler alternative exists, such as a class decorator or a base class with __init_subclass__.

The __init_subclass__ hook, introduced in Python 3.6, covers many use cases that previously required a metaclass. It is called when a subclass is defined, and it is easier to understand because it lives on the base class rather than a separate metaclass. For example, the registration pattern above can be implemented with __init_subclass__:

python
class Base: registry = [] def __init_subclass__(cls, **kwargs): super().__init_subclass__(**kwargs) Base.registry.append(cls)

This is often clearer and avoids the extra metaclass layer. Use a metaclass when you need to run logic for the base class itself, not just its subclasses; use __new__ if the logic must modify the class dictionary before creation, and __init__ for post-creation work.

When to Avoid Metaclass __init__

Metaclass __init__ is not the right tool for every class customization task. If you only need to add a few methods or attributes to a class, a class decorator is simpler and more explicit. If you need to react to subclass creation, __init_subclass__ is more direct. If you need to modify the class namespace before the class is created, you must use __new__, not __init__.

Metaclasses also introduce an extra level of indirection that can make code harder to debug. When a class is created through a metaclass, the flow is less obvious, and tools like IDEs may not resolve attributes as easily. Reserve metaclass __init__ for cases where the abstraction genuinely reduces duplication or enforces important invariants across many classes.

A final consideration is compatibility. Metaclass behavior is stable in modern Python, but the __init_subclass__ alternative is only available in Python 3.6 and later. If you are supporting older versions, a metaclass may be necessary. Otherwise, prefer the more explicit and maintainable options that Python provides today.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.