What is init.py for in Python?

In Python, the __init__.py file serves several key purposes for structuring packages and modules. Here’s a detailed breakdown of its role and usage:

1. Declares a Directory as a Python Package

Primary Purpose: A directory containing an __init__.py file is recognized by Python as a package, allowing you to import modules/subpackages from it.
Example:

  my_package/
    ├── __init__.py    # Required for Python to treat `my_package` as a package
    ├── module1.py
    └── subpackage/
        ├── __init__.py
        └── module2.py

2. Initializes Package-Level Code

Code inside __init__.py runs once when the package is imported. Use it for:
Package-level initialization (e.g., configuring resources).
Defining variables/functions accessible at the package level.

  # my_package/__init__.py
  print("Initializing my_package")

  from .module1 import MyClass  # Expose MyClass directly from the package

3. Controls Imports with `all`

Use __all__ to specify which modules are imported when using from package import *.

  # my_package/__init__.py
  __all__ = ["module1", "subpackage"]  # Limits wildcard imports to these modules

4. Simplifies User Imports

Expose submodule contents directly at the package level for easier access:

  # my_package/__init__.py
  from .module1 import my_function

Users can then import directly:

  from my_package import my_function  # Instead of `from my_package.module1 import my_function`

5. Namespace Packages (Python 3.3+)

In Python 3.3+, __init__.py is optional for “namespace packages” (split across multiple directories). However:
Best Practice: Include __init__.py for explicit package declaration and backward compatibility.

Examples

Empty `init.py`

# Minimal requirement to mark a directory as a package.

Initialize Package Data

# my_package/__init__.py
DB_CONFIG = {"host": "localhost", "port": 5432}

Expose Submodule Components

# my_package/__init__.py
from .subpackage.module2 import helper_function

Key Notes

Legacy Code: Older Python versions (pre-3.3) require __init__.py for packages.
Subpackages: Each subdirectory in a package should also have its own __init__.py.
Execution Order: Code in __init__.py runs when the package is first imported.

By using __init__.py, you organize code into reusable, modular components and define clear interfaces for users.