How to Implement a Singleton in Python: Patterns, Tradeoffs, and Pythonic Alternatives

By the end of this page, you will understand what a singleton is in Python, how modules, __new__, decorators, and metaclasses can be used to implement it, and why Python developers often prefer simpler alternatives. You will also see the practical tradeoffs between a "true singleton class" and a module-level shared object.

A singleton is a pattern that ensures only one instance of something exists during a program's lifetime, while providing a global way to access it.

In Python, this idea appears often in things like:

• application configuration
• database connection managers
• logging helpers
• caches
• service registries

The important Python-specific detail is this:

• In many languages, singleton patterns are built into class design.
• In Python, modules are already singletons in practice because a module is imported once and then reused.

That is why many Python developers ask a different question:

Do you really need a singleton class, or do you just need one shared object?

Why this matters

Choosing the wrong implementation can make code harder to understand.

For example:

• A decorator that turns a class into a function can break class behavior.
• A metaclass can work, but may be harder for beginners to read.
• A module-level instance is simple and unsurprising.

In Python, the most Pythonic solution is usually the one that is:

• easiest to read
• easiest to test
• least magical
• least likely to surprise other developers

So the real lesson is not just how to build a singleton, but when a simpler shared-object design is better.

Think of a singleton like a single reception desk in an office.

• Many people can ask for the desk.
• But the office should not create a new reception desk each time.
• Everyone is directed to the same one.

In Python, a module is like the building directory that already points everyone to the same desk.

A singleton class is more like adding a guard who checks:

• "Has the desk already been created?"
• If yes, return the existing one.
• If not, create it once.

The simpler the guard system, the easier it is for everyone else in the office to understand what is happening.

1. Simplest Pythonic approach: module-level instance

# logger_service.py

class Logger:
    def log(self, message):
        print(f"LOG: {message}")


logger = Logger()

Use it like this:

from logger_service import logger

logger.log("Application started")

Why this is often preferred

• The module is imported once.
• logger is created once.
• Other files reuse the same object.
• It is easy to understand.

2. Singleton with __new__

class Logger:
    _instance = None

    def __new__(cls, *args, **kwargs):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self):
        print("__init__ called")

Usage:

a = Logger()
b = Logger()

print(a is b)  # True

Important note

__new__ controls object creation, but __init__ may still run every time you call Logger() unless you guard against repeated initialization.

Example with safe one-time initialization:

class Logger:
    _instance = None
    _initialized = False

    def __new__(cls, *args, **kwargs):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self):
        if self._initialized:
            return
        self.logs = []
        self._initialized = True

3. Singleton with a metaclass

class SingletonMeta(type):
    _instances = {}

    def __call__(cls, *args, **kwargs):
        if cls not in cls._instances:
            cls._instances[cls] = super().__call__(*args, **kwargs)
        return cls._instances[cls]


class Logger(metaclass=SingletonMeta):
    def __init__(self):
        self.logs = []

Usage:

a = Logger()
b = Logger()

print(a is b)  # True

This keeps Logger as a real class and is cleaner than turning the class into a function with a decorator.

4. Decorator approach that replaces the class

def singleton(cls):
    instance = None

    def wrapper(*args, **kwargs):
        nonlocal instance
        if instance is None:
            instance = cls(*args, **kwargs)
        return instance

    return wrapper

This works for returning one instance, but it changes the decorated class name into a callable wrapper rather than preserving normal class behavior. That makes it less suitable when you want normal class semantics.

Consider this example using __new__:

class Config:
    _instance = None
    _initialized = False

    def __new__(cls):
        if cls._instance is None:
            print("Creating instance")
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self):
        if self._initialized:
            print("Already initialized")
            return
        print("Running initialization")
        self.settings = {"theme": "dark"}
        self._initialized = True


x = Config()
y = Config()

print(x is y)
print(x.settings)

What happens step by step

1. x = Config() is executed.
2. Python calls Config.__new__(Config).
3. _instance is None, so a new object is created.
4. Python then calls Config.__init__(x).
5. _initialized is False, so initialization runs and settings is created.
6. y = Config() is executed.
7. Python calls Config.__new__(Config) again.
8. _instance already exists, so the same object is returned.
9. Python still calls Config.__init__(y).
10. Because _initialized is now True, initialization is skipped.
11. x is y prints True.
12. x.settings prints {'theme': 'dark'}.

Expected output

Creating instance
Running initialization
Already initialized
True
{'theme': 'dark'}

Shared configuration

A program may load configuration once and reuse it everywhere.

class AppConfig:
    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance.debug = True
        return cls._instance

Logging service

A single logger object can collect messages from different parts of the app.

Cache manager

A shared in-memory cache avoids creating separate caches in each module.

Database connection coordinator

Sometimes an app wants one connection manager object, even if the manager itself internally controls a pool.

Feature flag registry

A shared service can expose flags like is_beta_enabled across the application.

In practice, many of these are simpler as module-level objects rather than formal singleton classes.

In real projects, developers often use one of these patterns instead of a heavy singleton implementation:

Module-level shared object

# config.py
settings = {"debug": True}

This is the most common and readable option when one shared object is enough.

Lazy module-level factory

_instance = None


def get_logger():
    global _instance
    if _instance is None:
        _instance = Logger()
    return _instance

This gives lazy initialization without metaclasses.

Dependency injection

Instead of global access, the object is created once and passed where needed.

class UserService:
    def __init__(self, logger):
        self.logger = logger

This is common in testable codebases because it avoids hidden global state.

Guarded initialization

If using __new__, developers commonly add an initialization guard.

Validation and error handling

Singleton-like services often validate startup configuration once, then raise a clear error if setup is invalid.

Why metaclasses are less common

Metaclasses can be correct, but many teams avoid them unless they truly need class-level customization, because they increase mental overhead for readers.

Mistake 1: Forgetting that __init__ can run more than once

Broken example:

class Logger:
    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self):
        self.logs = []

Problem:

• Every call to Logger() resets self.logs.

Fix:

class Logger:
    _instance = None
    _initialized = False

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self):
        if self._initialized:
            return
        self.logs = []
        self._initialized = True

Mistake 2: Using == instead of is

a = Logger()
b = Logger()

print(a == b)

Problem:

• == checks value equality.
• is checks whether both names refer to the exact same object.

Use this:

print(a is b)

Mistake 3: Replacing the class with a function unintentionally

A decorator-based singleton may make this fail in surprising ways:

@singleton
class MyClass:
    pass

print(type(MyClass))

Now MyClass may be a function-like wrapper, not the original class.

Mistake 4: Making code hard to test

Global singletons can leak state between tests.

Avoid this by:

• resetting shared state in tests
• using dependency injection when possible
• preferring simple factories for testable code

Mistake 5: Using a singleton where a module variable is enough

If all you need is one shared object, this is often simpler:

service = Service()

inside a module.

__new__ vs metaclass

Most Pythonic choice

For most code:

1. Module-level object if you just need one shared instance.
2. Module-level factory if you want lazy creation.
3. __new__ or metaclass only if you truly need singleton behavior at the class level.

Singleton quick reference in Python

Simplest shared object

# service.py
class Service:
    pass

service = Service()

Lazy shared object

_instance = None

def get_service():
    global _instance
    if _instance is None:
        _instance = Service()
    return _instance

__new__ singleton

class Service:
    _instance = None
    _initialized = False

    def __new__(cls, *args, **kwargs):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __init__(self):
        if self._initialized:
            return
        self._initialized = True

Metaclass singleton

class SingletonMeta(type):
    _instances = {}

    def __call__(cls, *args, **kwargs):
        if cls not in cls._instances:
            cls._instances[cls] = super().__call__(*args, **kwargs)
        return cls._instances[cls]

Key rules

• Use is, not ==, to verify singleton identity.
• __new__ creates the object; __init__ initializes it.
• __init__ may run multiple times unless guarded.
• Modules already act like shared singletons in normal imports.
• Prefer the least surprising design.

Edge cases

• Singletons can make tests harder.
• In multithreaded code, extra locking may be needed.
• Decorators that replace the class can break introspection and class methods.

Why are modules often considered singletons in Python?

Because Python imports a module once and then reuses the same module object, so module-level state is naturally shared.

Is using a metaclass the best way to implement a singleton in Python?

Not always. It is powerful, but often more complex than necessary. A module-level object or factory is usually simpler.

What is the difference between __new__ and __init__ in a singleton?

__new__ controls object creation. __init__ configures the object after creation. In a singleton, __init__ may be called multiple times unless you guard it.

How do I check whether two singleton variables are the same object?

Use is:

a is b

Are singletons bad in Python?

Not automatically, but they can introduce hidden global state and make testing harder. Use them only when shared state is truly needed.

What is the most Pythonic singleton alternative?

Usually a module-level instance or a module-level getter function.

Can a decorator-based singleton break my class?

Yes. If the decorator returns a function wrapper, the original class identity and behavior may be lost.

Should I use a singleton for logging in Python?

Often no. Python's built-in logging module already manages shared logger behavior well.

• Modules in Python — modules already provide shared state and are often the simplest singleton alternative.
• __new__ method — important for controlling object creation.
• __init__ method — important because repeated initialization can cause bugs in singleton designs.
• Metaclasses — useful when changing class construction behavior for many classes.
• Decorators — relevant because they can modify or wrap class behavior.
• Class attributes vs instance attributes — singleton implementations often rely on class attributes like _instance.
• Global state — singletons are a controlled form of global shared state.
• Dependency injection — a common alternative that improves testing and flexibility.