A Guide to Python's __init__.py

If you've spent any time browsing Python projects, you've undoubtedly come across a file named __init__.py. It's often empty, yet it plays a crucial role in how Python structures and imports code. Let's break down exactly what this special file does.

The Primary Role: Marking a Directory as a Package

The most fundamental purpose of __init__.py is to tell the Python interpreter that a directory should be treated as a package.

Consider this directory structure:

my_project/
├── main.py
└── my_package/
    ├── __init__.py
    └── module1.py

Because my_package/ contains an __init__.py file, Python recognizes it as a package. This allows you to import modules from it in other files, like main.py:

# main.py
from my_package import module1

module1.some_function()

If you were to remove __init__.py from my_package/, this import would fail with a ModuleNotFoundError in older versions of Python (before 3.3).

A Note on Modern Python: Implicit Namespace Packages

Since Python 3.3 (as defined in PEP 420), directories without an __init__.py file can still be treated as packages. These are called "implicit namespace packages." While this is a powerful feature for building large, distributable libraries, it's still a common and recommended practice to include an __init__.py file in your regular packages. It makes the package structure explicit and serves as a clear signal to other developers.

The Secondary Role: Package Initialization and Public API

While often empty, the __init__.py file is a fully functional Python module. The code inside it is executed the first time any module within the package is imported. This allows you to perform two useful tasks:

1. Package-level Initialization: You can run initialization code for your package. For example, you could set up logging or connect to a database, although this is less common.

2. Defining a Public API: This is the most powerful use case. You can use __init__.py to control what names are exposed when a user imports your package, creating a cleaner and more convenient API.

Let's expand our example:

my_package/
├── __init__.py
├── module1.py
└── module2.py

# my_package/module1.py
def function_a():
    print("Hello from function A")

class ClassA:
    pass

# my_package/module2.py
def _internal_helper():
    # This is not meant for external use
    pass

def function_b():
    print("Greetings from function B")

Without any changes, a user would have to import specific functions like this:

from my_package.module1 import function_a
from my_package.module2 import function_b

function_a()
function_b()

This is verbose. We can make it cleaner by importing these names into the package's namespace in __init__.py.

# my_package/__init__.py

# Promote key functions and classes to the top-level package namespace
from .module1 import function_a, ClassA
from .module2 import function_b

print("my_package has been initialized")

Now, the user's import becomes much simpler:

# main.py
from my_package import function_a, function_b, ClassA

# The print statement in __init__.py runs once on the first import
# Output: my_package has been initialized

function_a()
function_b()

By doing this, you've created a clean public API for your package. The user doesn't need to know about the internal structure (module1, module2). They can just import everything they need directly from my_package.

Controlling import * with __all__

While from my_package import * is generally discouraged, you can control what gets imported by defining a list called __all__ in your __init__.py.

# my_package/__init__.py
from .module1 import function_a, ClassA
from .module2 import function_b

# Only these names will be imported with 'from my_package import *'
__all__ = ['function_a', 'function_b']

Now, if a user does from my_package import *, they will only get function_a and function_b. ClassA will not be imported.

Conclusion

• Required (Historically): __init__.py marks a directory as a regular Python package.
• Optional (Functionally): You can use it to run initialization code for your package.
• Recommended (For API Design): Use it to create a clean public API for your package by importing key functions and classes into the package's top-level namespace.

Even when it's empty, __init__.py is a powerful and important part of Python's module system.