Every class you have ever written in Python is an instance of something. Not an instance of itself -- an instance of type. Sit with that for a second. The integer 42 is an instance of int. The class int is an instance of type. And type is an instance of... type. It's turtles all the way down, except the bottom turtle is standing on itself.
I spent years writing Python before metaclasses actually clicked for me. Not because they are inherently difficult -- they aren't -- but because every tutorial I read started with the wrong framing. They'd begin with "a metaclass is a class whose instances are classes" and then immediately jump to some contrived example that validated attribute names. Nobody told me why I'd want this. Nobody showed me the moment where the lightbulb goes on and you realize metaclasses let you hook into the class creation protocol itself, intercepting the birth of every class before a single instance is ever created.
Today I want to fix that. We're going to build a self-registering plugin system from scratch, the kind of thing you'd find inside Django, Flask, or pytest. By the end, you'll understand the full type creation protocol, know exactly when metaclasses are the right tool (and when they aren't), and have real code you can drop into your own projects.
Most explanations fail because they treat metaclasses as an abstract concept rather than a concrete mechanism. So let's be concrete.
When Python encounters a class statement like this:
class Dog:
sound = "woof"
def speak(self):
return self.sound
It does not just "define a class." It executes a precise sequence of operations. First, it executes the class body as a code block, collecting all the names (sound, speak) into a dictionary. Then it calls type("Dog", (), {"sound": "woof", "speak": <function>}). That call to type is what actually creates the class object. The class statement is syntactic sugar for a function call.
You can verify this yourself:
# These two are equivalent
class Dog:
sound = "woof"
Dog2 = type("Dog2", (), {"sound": "woof"})
print(type(Dog)) # <class 'type'>
print(type(Dog2)) # <class 'type'>
print(Dog.sound) # woof
print(Dog2.sound) # woof
A metaclass is simply a callable that gets invoked instead of type during this process. When you write class Dog(metaclass=MyMeta), Python calls MyMeta("Dog", (,), {...}) instead of type("Dog", (,), {...}). That's it. A metaclass is a factory for classes, the same way a class is a factory for instances.
The reason this is powerful is timing. A decorator modifies a class after it's been created. A metaclass participates in the creation itself. It's the difference between renovating a house after construction and being the architect who draws the blueprints.
To write a metaclass, you need to understand three methods on type and how they differ. This is where most tutorials get hand-wavy. Let's not.
__new__(cls, name, bases, namespace) is called first. It is responsible for creating and returning the new class object. This is where the class literally comes into existence. If you want to modify the class's attributes, inject methods, or alter the inheritance chain, this is your hook.
__init__(cls, name, bases, namespace) is called after __new__ returns. The class object already exists at this point. You use __init__ for any post-creation setup that doesn't require modifying the class object's structure -- think bookkeeping, registration, validation.
__call__(cls, *args, **kwargs) is different entirely. It fires not when the class is created, but when the class is instantiated. When someone writes dog = Dog(), Python calls type.__call__(Dog), which in turn calls Dog.__new__ and Dog.__init__. Override this in a metaclass to control how instances of the class are born.
Here's a minimal metaclass that demonstrates all three:
class VerboseMeta(type):
def __new__(mcs, name, bases, namespace):
print(f"__new__: Creating class '{name}'")
cls = super().__new__(mcs, name, bases, namespace)
return cls
def __init__(cls, name, bases, namespace):
print(f"__init__: Initializing class '{name}'")
super().__init__(name, bases, namespace)
def __call__(cls, *args, **kwargs):
print(f"__call__: Instantiating '{cls.__name__}'")
return super().__call__(*args, **kwargs)
class Animal(metaclass=VerboseMeta):
pass
# Output:
# __new__: Creating class 'Animal'
# __init__: Initializing class 'Animal'
a = Animal()
# Output:
# __call__: Instantiating 'Animal'
Notice: __new__ and __init__ fire at class definition time (when Python reads the class Animal statement). __call__ fires at instantiation time (when you actually create an Animal()). This distinction matters enormously for plugin systems, because we want to register classes when they're defined, not when they're instantiated.
Here's the real payoff. Imagine you're building an image processing pipeline. You have a base Filter class, and you want third-party developers to create their own filters by simply subclassing. No manual registration, no configuration files, no decorators. Just define a subclass and it appears in the system.
This is the registry pattern, and it's everywhere in production Python -- Django models, Flask extensions, pytest fixtures, SQLAlchemy column types.
class PluginRegistry(type):
"""Metaclass that automatically registers all non-abstract subclasses."""
_registry: dict[str, type] = {}
def __new__(mcs, name, bases, namespace):
cls = super().__new__(mcs, name, bases, namespace)
# Don't register the base class itself
if bases:
# Use the class name as the registry key, or a custom 'name' attribute
plugin_name = namespace.get("name", name.lower())
mcs._registry[plugin_name] = cls
return cls
@classmethod
def get_registry(mcs):
return dict(mcs._registry)
@classmethod
def create(mcs, name, *args, **kwargs):
"""Factory method: create a plugin instance by name."""
if name not in mcs._registry:
raise ValueError(
f"Unknown plugin '{name}'. "
f"Available: {list(mcs._registry.keys())}"
)
return mcs._registry[name](*args, **kwargs)
class Filter(metaclass=PluginRegistry):
"""Base class for all image filters."""
def apply(self, image):
raise NotImplementedError
class Sharpen(Filter):
name = "sharpen"
def __init__(self, strength=1.0):
self.strength = strength
def apply(self, image):
return f"Sharpening with strength {self.strength}"
class Blur(Filter):
name = "blur"
def __init__(self, radius=5):
self.radius = radius
def apply(self, image):
return f"Blurring with radius {self.radius}"
class Grayscale(Filter):
name = "grayscale"
def apply(self, image):
return "Converting to grayscale"
# The magic: all subclasses registered automatically
print(PluginRegistry.get_registry())
# {'sharpen': <class 'Sharpen'>, 'blur': <class 'Blur'>, 'grayscale': <class 'Grayscale'>}
# Factory creation by string name
f = PluginRegistry.create("blur", radius=10)
print(f.apply(None))
# Blurring with radius 10
The moment class Sharpen(Filter) is evaluated by Python, PluginRegistry.__new__ fires and adds it to the registry. No imports to remember. No registration decorators to forget. No YAML config to keep in sync. The class's mere existence is its registration.
This pattern scales beautifully. Your plugin authors can put their filter in a separate package, and as long as that package gets imported somewhere (an __init__.py, a config-driven plugin loader, an entry point), the class registers itself.
Python 3.6 introduced __init_subclass__ via PEP 487, and it covers roughly 90% of what people actually use metaclasses for. The motivation was exactly the pattern we just built -- you shouldn't need to understand the full metaclass machinery just to react to subclassing.
Here's the same plugin system, rewritten:
class Filter:
"""Base class for all image filters using __init_subclass__."""
_registry: dict[str, type] = {}
def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)
plugin_name = getattr(cls, "name", cls.__name__.lower())
cls._registry[plugin_name] = cls
@classmethod
def get_registry(cls):
return dict(cls._registry)
@classmethod
def create(cls, name, *args, **kwargs):
if name not in cls._registry:
raise ValueError(
f"Unknown plugin '{name}'. "
f"Available: {list(cls._registry.keys())}"
)
return cls._registry[name](*args, **kwargs)
def apply(self, image):
raise NotImplementedError
class Sharpen(Filter):
name = "sharpen"
def __init__(self, strength=1.0):
self.strength = strength
def apply(self, image):
return f"Sharpening with strength {self.strength}"
class Blur(Filter):
name = "blur"
def __init__(self, radius=5):
self.radius = radius
def apply(self, image):
return f"Blurring with radius {self.radius}"
print(Filter.get_registry())
# {'sharpen': <class 'Sharpen'>, 'blur': <class 'Blur'>}
print(Filter.create("sharpen", strength=2.0).apply(None))
# Sharpening with strength 2.0
Functionally identical. The __init_subclass__ hook fires every time a class inherits from Filter, and we register it. The code is shorter, easier to read, and -- critically -- avoids the metaclass conflict problem.
What's the metaclass conflict problem? If your plugin base class uses PluginRegistry as its metaclass, and a user wants their plugin to also inherit from an ABC (which uses ABCMeta as its metaclass), Python raises a TypeError:
TypeError: metaclass conflict: the metaclass of a derived class must be a
(non-strict) subclass of the metaclasses of all its bases
You'd have to create a combined metaclass that inherits from both PluginRegistry and ABCMeta. With __init_subclass__, this entire problem vanishes because you're not introducing a new metaclass at all.
The __init_subclass__ approach also supports passing keyword arguments through the class definition line, which is elegant for configuration:
class Serializer:
_formats: dict[str, type] = {}
def __init_subclass__(cls, format=None, **kwargs):
super().__init_subclass__(**kwargs)
if format is not None:
cls._formats[format] = cls
class JSONSerializer(Serializer, format="json"):
def serialize(self, data):
import json
return json.dumps(data)
class XMLSerializer(Serializer, format="xml"):
def serialize(self, data):
return f"<data>{data}</data>"
print(Serializer._formats)
# {'json': <class 'JSONSerializer'>, 'xml': <class 'XMLSerializer'>}
So if __init_subclass__ handles the registry pattern, when do you actually need a metaclass? I think about it in terms of four specific scenarios.
1. You need to modify the class before it's fully created. __init_subclass__ runs after type.__new__ has already built the class. If you need to transform the namespace dictionary before the class object exists -- rewriting attributes, injecting descriptors based on other attributes, changing the bases tuple -- you need __new__ on a metaclass.
2. You need to control __call__ (instance creation). Want to implement a singleton pattern, object pooling, or conditional instantiation based on the class itself? You need a metaclass __call__. __init_subclass__ has no hook into instantiation.
class SingletonMeta(type):
_instances: dict[type, object] = {}
def __call__(cls, *args, **kwargs):
if cls not in cls._instances:
cls._instances[cls] = super().__call__(*args, **kwargs)
return cls._instances[cls]
class DatabaseConnection(metaclass=SingletonMeta):
def __init__(self):
self.connected = True
print("Connecting to database...")
a = DatabaseConnection() # Connecting to database...
b = DatabaseConnection() # (no output -- same instance returned)
print(a is b) # True
3. You need __prepare__ to customize the namespace. The __prepare__ method lets you return a custom mapping object for the class body to execute in. Python's enum.Enum uses this to track definition order and prevent duplicate values. __init_subclass__ cannot do this.
4. You're building a framework where metaclass inheritance is actually desirable. When every subclass in a hierarchy must go through your creation logic, and you want this to be inescapable (not opt-in via remembering to call super().__init_subclass__), a metaclass propagates automatically through the inheritance chain.
For everything else, reach for __init_subclass__ first, class decorators second, and metaclasses last.
Understanding where metaclasses show up in real codebases solidifies the intuition for when they make sense.
Django's ModelBase is probably the most famous metaclass in the Python ecosystem. When you write class Article(models.Model), Django's metaclass processes the field descriptors, constructs the _meta options object, sets up the manager, registers the model with the app registry, and creates the database table mapping. None of this could work with a decorator, because the class needs to be fundamentally transformed during creation -- fields need to be moved from the class namespace to _meta.fields, descriptors need to be wired up, and reverse relations need to be registered on other classes.
Python's own ABCMeta tracks abstract methods across the inheritance hierarchy. When you declare @abstractmethod on a method and use ABCMeta as the metaclass, it scans __abstractmethods__ at class creation time and prevents instantiation of classes that haven't overridden all abstract methods. This needs to be a metaclass because it must intercept __call__ to raise TypeError on incomplete implementations.
SQLAlchemy's declarative base uses a metaclass to map Python classes to database tables. When you define columns as class attributes, the metaclass collects them, builds the table schema, and sets up the ORM mapping -- all at class definition time, before any queries run.
enum.EnumMeta uses __prepare__ to return an _EnumDict instead of a regular dict, which prevents duplicate member names and tracks definition order. It then uses __new__ to transform the namespace into enum members with values, names, and the iteration protocol. This is one of the cleanest examples of a metaclass doing something that genuinely cannot be done any other way.
A pattern I've found useful in my own work is combining __init_subclass__ for the simple cases (registration, validation) with a metaclass only when I need __call__ or __prepare__:
import abc
class CommandBase:
"""Simple command registration using __init_subclass__."""
_commands: dict[str, type] = {}
def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)
if not getattr(cls, "__abstractmethods__", None):
cmd_name = getattr(cls, "name", cls.__name__.lower())
cls._commands[cmd_name] = cls
@abc.abstractmethod
def execute(self, args: list[str]) -> str:
...
@classmethod
def dispatch(cls, command: str, args: list[str]) -> str:
if command not in cls._commands:
available = ", ".join(cls._commands.keys())
raise ValueError(f"Unknown command '{command}'. Available: {available}")
return cls._commands[command]().execute(args)
class GreetCommand(CommandBase):
name = "greet"
def execute(self, args):
name = args[0] if args else "World"
return f"Hello, {name}!"
class ExitCommand(CommandBase):
name = "exit"
def execute(self, args):
return "Goodbye!"
# Auto-registered
print(CommandBase._commands)
# {'greet': <class 'GreetCommand'>, 'exit': <class 'ExitCommand'>}
print(CommandBase.dispatch("greet", ["Andrej"]))
# Hello, Andrej!
The mental model I keep coming back to is this: Python's class creation is a protocol with well-defined extension points. __init_subclass__ is the lightweight hook for reacting to subclassing. Class decorators are the post-processing step. Metaclasses are the nuclear option -- they give you total control over the factory itself.
Most of the time, you don't need to rebuild the factory. You just need a hook on the assembly line. But when you do need to rebuild it -- when you're building Django, or SQLAlchemy, or a new kind of type system entirely -- metaclasses are sitting there, waiting, an instance of type all the way down.