What Are Metaclasses in Python? A Beginner-Friendly Guide

By the end of this page, you will understand that metaclasses are the mechanism Python uses to create classes. You will see how objects are created from classes, how classes themselves are created by metaclasses, and why metaclasses are mainly used to customize class creation. You will also learn common use cases, examples, mistakes to avoid, and when simpler alternatives are better.

In Python, a metaclass is a class whose job is to create other classes.

Most beginners are familiar with this idea:

• an object is created from a class
• for example, user = User() creates an object from the User class

But Python goes one level higher:

• a class is also an object in Python
• since classes are objects, they must also be created by something
• that something is a metaclass

By default, Python uses the built-in metaclass type to create classes.

For example:

class User:
    pass

This class definition is roughly similar to:

User = type("User", (), {})

Here:

• "User" is the class name
• () is the tuple of base classes
• {} is the class namespace

So type is doing two jobs in Python:

• it tells you the type of an object: type(5)
• it creates classes: type("User", (), {})

Why metaclasses matter

Metaclasses matter because they let you control how classes are built.

That means you can:

• validate class definitions
• automatically add methods or attributes
• register classes in a central registry
• enforce coding rules across many classes
• modify inheritance behavior at class creation time

This is powerful, but it is also advanced. In real code, many problems can be solved more simply with:

• regular base classes
• class decorators
• factory functions
• __init_subclass__

So metaclasses are useful, but they are not something you need every day.

The key hierarchy

A useful way to view Python is:

• instance → created from a class
• class → created from a metaclass

Example:

class Product:
    pass

item = Product()

print(type(item))      # <class '__main__.Product'>
print(type(Product))   # <class 'type'>

This shows:

• item is an instance of Product
• Product is an instance of type

Custom metaclasses

You can define your own metaclass by inheriting from type.

The most common customization point is __new__, which runs when the class itself is being created.

Example:

class UpperAttrMeta(type):
    def __new__(mcls, name, bases, namespace):
        new_namespace = {}
        for key, value in namespace.items():
            if not key.startswith("__"):
                new_namespace[key.upper()] = value
            else:
                new_namespace[key] = value
        return super().__new__(mcls, name, bases, new_namespace)


class Example(metaclass=UpperAttrMeta):
    message = "hello"


print(hasattr(Example, "message"))  # False
print(hasattr(Example, "MESSAGE"))  # True
print(Example.MESSAGE)               # hello

This metaclass changes the class before Python finishes creating it.

What metaclasses are used for

Common reasons to use metaclasses include:

• validation: require certain methods or attributes on all subclasses
• registration: automatically keep track of subclasses
• framework behavior: ORMs, serializers, admin systems, and plugin systems sometimes inspect class bodies
• automatic modification: inject methods, properties, or configuration into classes

Important note

Metaclasses are often described as “deep magic” in Python because they are powerful but can make code harder to understand. If a simpler tool works, prefer the simpler tool.

Think of Python as a factory system with three layers:

• Objects are the products
• Classes are the machines that make those products
• Metaclasses are the machines that build the machines

So if a class is a machine that creates objects, a metaclass is the blueprint system that decides how those machines are built.

Example:

• Car() creates a car object
• Car is a class
• type created the Car class

A custom metaclass is like having a special factory supervisor that says:

• every machine must have a label
• every machine must register itself
• every machine should get an extra feature automatically

You usually do not need to manage the factory supervisor yourself, but Python gives you that power when necessary.

Basic syntax

A custom metaclass usually inherits from type:

class MyMeta(type):
    def __new__(mcls, name, bases, namespace):
        # modify or validate the class definition here
        return super().__new__(mcls, name, bases, namespace)

Then use it in a class:

class MyClass(metaclass=MyMeta):
    pass

Example 1: Add an attribute automatically

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


class APIClient(metaclass=AddVersionMeta):
    pass


print(APIClient.version)  # 1.0

Explanation

Before APIClient is fully created, the metaclass adds a class attribute called version.

Example 2: Validate class contents

class RequireSaveMeta(type):
    def __new__(mcls, name, bases, namespace):
        if "save" not in namespace:
            raise TypeError(f"{name} must define a save() method")
        return super().__new__(mcls, name, bases, namespace)


class Document(metaclass=RequireSaveMeta):
    def save(self):
        print("Saving document")

This works because Document defines save.

If you wrote this instead:

class BrokenDocument(metaclass=RequireSaveMeta):
    pass

Python would raise a TypeError when the class is created.

Example 3: Show that classes are instances of type

class Animal:
    pass

pet = Animal()

print(type(pet))     # <class '__main__.Animal'>
print(type(Animal))  # <class 'type'>

This is the foundation for understanding metaclasses.

Consider this example:

class AddGreetingMeta(type):
    def __new__(mcls, name, bases, namespace):
        namespace["greeting"] = "Hello"
        return super().__new__(mcls, name, bases, namespace)


class Person(metaclass=AddGreetingMeta):
    age = 25

Here is what happens step by step:

1. Python starts reading the Person class body.
2. It collects the class contents into a namespace dictionary.
   • At this point, the namespace contains roughly:

{
    "__module__": "__main__",
    "__qualname__": "Person",
    "age": 25
}

1. Python sees metaclass=AddGreetingMeta.
2. Instead of using plain type directly, Python calls AddGreetingMeta.__new__.
3. Inside __new__, the metaclass adds:

namespace["greeting"] = "Hello"

1. The metaclass calls super().__new__(...) to actually create the class object.
2. The final Person class now contains:
   • age = 25
   • greeting = "Hello"
3. You can use the class normally:

print(Person.age)       # 25
print(Person.greeting)  # Hello

Important detail

The metaclass runs when the class is defined, not when an instance is created.

So this happens once:

class Person(metaclass=AddGreetingMeta):
    pass

But this is normal instance creation afterward:

p = Person()

Metaclasses are not common in everyday scripts, but they do appear in frameworks and reusable libraries.

1. Automatically registering subclasses

A plugin system may want every plugin class to register itself automatically.

class RegistryMeta(type):
    registry = {}

    def __new__(mcls, name, bases, namespace):
        cls = super().__new__(mcls, name, bases, namespace)
        mcls.registry[name] = cls
        return cls

This is useful for:

• plugin loaders
• command systems
• serializers
• job runners

2. Enforcing framework rules

A framework might require all model classes to define certain fields or methods.

Examples:

• ORM models must define metadata
• command classes must implement run()
• API handlers must specify allowed methods

3. Building classes from declarations

Some frameworks inspect class attributes to build behavior.

For example, a form or ORM system might read:

class UserForm:
    name = "text field"
    email = "email field"

A metaclass can collect those definitions and prepare the class automatically.

4. Automatic class modification

A library may inject:

• default configuration
• helper methods
• generated properties
• validation logic

This can reduce repeated boilerplate across many classes.

5. Large reusable libraries

Metaclasses are most useful when building tools that other developers use, especially when class definitions themselves are part of the API.

In real projects, metaclasses are usually used carefully and only where class creation needs to be customized.

Common patterns

Registration pattern

Libraries often register subclasses automatically.

class BaseMeta(type):
    registry = {}

    def __new__(mcls, name, bases, namespace):
        cls = super().__new__(mcls, name, bases, namespace)
        if name != "Base":
            mcls.registry[name] = cls
        return cls

This avoids manual registration code in every subclass.

Validation at class definition time

Instead of waiting for runtime errors later, a metaclass can fail early.

class EndpointMeta(type):
    def __new__(mcls, name, bases, namespace):
        cls = super().__new__(mcls, name, bases, namespace)
        if name != "BaseEndpoint" and not hasattr(cls, "path"):
            raise TypeError(f"{name} must define 'path'")
        return cls

This acts like a guard clause for class definitions.

Declarative class APIs

Frameworks sometimes let developers define behavior by writing class attributes. A metaclass reads those attributes and transforms them into internal configuration.

This is common in:

• ORM-style models
• serializers
• forms
• command dispatch systems

Simpler alternatives used more often

In many modern codebases, developers prefer simpler tools first:

• __init_subclass__ for subclass hooks
• class decorators for class transformation
• base classes for shared behavior
• regular functions for validation and setup

These are often easier to read than a full metaclass.

Practical advice

If your codebase has a metaclass, it is usually doing one of these jobs:

• enforcing structure
• collecting class metadata
• auto-registering classes
• generating class-level behavior

If you are just writing application code, you may rarely need to create one yourself.

1. Using metaclasses when a simpler tool is enough

Many beginners reach for metaclasses too early.

Often, this is enough:

• a base class
• a class decorator
• __init_subclass__

Use a metaclass only when you truly need to customize class creation.

2. Confusing classes with instances

Broken thinking:

class User:
    pass

print(type(User()))  # instance type
print(type(User))    # class type

Remember:

• User() is an instance
• User is a class object
• type creates classes by default

3. Forgetting to call super().__new__

Broken example:

class BrokenMeta(type):
    def __new__(mcls, name, bases, namespace):
        namespace["x"] = 1
        # missing return of actual class creation

This will break class creation.

Correct version:

class WorkingMeta(type):
    def __new__(mcls, name, bases, namespace):
        namespace["x"] = 1
        return super().__new__(mcls, name, bases, namespace)

4. Modifying special attributes carelessly

Special names like __module__, __qualname__, and dunder methods have meaning.

If you rewrite them by accident, class behavior may become confusing.

5. Making code too magical

A metaclass can silently change how a class works. That may confuse other developers.

Avoid surprising behavior unless the benefit is clear and well documented.

6. Metaclass conflicts in multiple inheritance

If two parent classes use incompatible metaclasses, Python may raise a metaclass conflict error.

This is one reason metaclasses can make inheritance more complex.

7. Expecting metaclass logic to run on every instance creation

Metaclass logic usually runs when the class is defined, not every time you create an object.

class MyMeta(type):
    def __new__(mcls, name, bases, namespace):
        print("Creating class")
        return super().__new__(mcls, name, bases, namespace)


class Example(metaclass=MyMeta):
    pass


a = Example()
b = Example()

Creating class prints once, when Example is created.

Metaclass vs class vs instance

type as type checker vs class creator

Metaclass vs class decorator vs __init_subclass__

Metaclass vs regular __init__

When to choose what

• Use a base class for shared methods and behavior.
• Use __init_subclass__ when you want to react to subclasses being defined.
• Use a class decorator for straightforward class transformation.
• Use a metaclass only when you need low-level control over class creation.

Core idea

• Objects are created from classes.
• Classes are created from metaclasses.
• The default metaclass in Python is type.

Key checks

class A:
    pass

a = A()

print(type(a))  # <class '__main__.A'>
print(type(A))  # <class 'type'>

Create a class manually

A = type("A", (), {})

Custom metaclass syntax

class MyMeta(type):
    def __new__(mcls, name, bases, namespace):
        # inspect or modify namespace
        return super().__new__(mcls, name, bases, namespace)


class MyClass(metaclass=MyMeta):
    pass

Common uses

• validate class definitions
• auto-register subclasses
• add class attributes or methods
• process declarative class attributes

Important rules

• Metaclasses usually inherit from type.
• They act during class creation, not normal instance creation.
• Always return the class from super().__new__(...).
• Prefer simpler tools first when possible.

Good alternatives

• base classes
• class decorators
• __init_subclass__

Warning signs

• code becomes hard to read
• behavior is too magical
• inheritance introduces metaclass conflicts

What is a metaclass in Python in simple terms?

A metaclass is the thing that creates classes. Just as classes create objects, metaclasses create classes.

Is type a metaclass in Python?

Yes. The built-in type is Python's default metaclass.

Do I need metaclasses for normal Python programs?

Usually no. Most programs work fine with regular classes, functions, decorators, or __init_subclass__.

Why would someone use a metaclass?

To customize class creation, such as validating class definitions, registering subclasses, or automatically adding class-level behavior.

Are metaclasses the same as inheritance?

No. Inheritance lets one class reuse or extend another. A metaclass controls how a class itself is built.

When does a metaclass run?

It runs when Python creates the class, usually at import time or when the class definition is executed.

Can metaclasses make code harder to understand?

Yes. They are powerful but can introduce hidden behavior. Use them carefully and only when they solve a real need.

What should I learn before metaclasses?

You should be comfortable with classes, objects, inheritance, class attributes, and the built-in type() function.

• Classes and objects — Metaclasses make more sense once you understand how classes create instances.
• type() function — type is the default metaclass, so it is central to the topic.
• Inheritance — Metaclasses often appear in class hierarchies and can affect subclass behavior.
• Class attributes — Many metaclass examples inspect or modify class-level attributes.
• __new__ and __init__ — Metaclasses commonly customize class creation through __new__.
• __init_subclass__ — A simpler alternative for some subclass customization tasks.
• Class decorators — Another way to modify classes without using a metaclass.
• Descriptors — Often used in frameworks that also rely on metaclasses for class processing.