When You Need init.py

Mental Model

Consider __init__.py as a package's "birth certificate" or "welcome mat." Without it, a directory containing Python files is just a folder. With it, Python recognizes it as a formal package, allowing it to have an __path__ attribute and be properly discovered, walked, and imported as a cohesive unit.

Rule: Always place __init__.py files inside your code directories to ensure they are parsed as regular packages with fully resolvable import paths.

The Setup

You have a monorepo setup with multiple services. You structure them into folders without __init__.py files, assuming modern Python handles namespaces seamlessly, only to discover your testing tool fails to find your packages.

What Does This Print?

⚠ Broken code

Python

# Directory layout:
# src/
#   utils/
#     math.py  # (No __init__.py present inside utils/ or src/)

import os
import pkgutil

# Try to discover submodules of our utils package programmatically
import src
try:
    package_names = [name for _, name, _ in pkgutil.walk_packages(src.__path__)]
    print("Discovered packages:", package_names)
except AttributeError as e:
    print(f"Discovery Failed: {e}")

What happens when you run this script? Will it print ['utils', 'utils.math']?

The Output

What actually happens

AttributeError: module 'src' has no attribute '__path__'

The discovery script crashes because the folder src does not contain an __init__.py file, transforming it into an implicit namespace package instead of a regular package. Regular packages are initialized immediately upon import, establishing a __path__ attribute. Implicit namespace packages lack these immediate initialization hooks, causing reflection and discovery tools to fail when searching for nested packages. This breaks static analysis tools, code coverages, and test discovery mechanisms that crawl directories looking for formal package structures. Without the presence of __init__.py, the directory is not recognized as a cohesive package unit by the standard libraries, causing silent module routing failures.

Why Python Does This

Python 3.3 introduced implicit namespace packages to allow developers to split a single package's submodules across multiple directories on disk. When CPython encounters a directory without an __init__.py file, it marks it as a namespace package and defers full initialization. Consequently, the imported module does not run any setup code, and its __path__ is represented by a special dynamic iterable rather than a standard list of directory strings. This prevents package crawlers like pkgutil from inspecting submodules unless the parent package is explicitly registered as a regular package through an empty __init__.py marker file.

The Fix

✓ Corrected pattern

Python

# Create an empty 'src/__init__.py' and 'src/utils/__init__.py'
# This turns them into formal regular packages.

import src
import pkgutil

# Regular packages have a defined __path__, allowing crawlers to walk them safely
package_names = [name for _, name, _ in pkgutil.walk_packages(src.__path__)]
print("Discovered packages:", package_names)  # Outputs ['utils', 'utils.math']

An __init__.py file (even an empty one) in a directory signals to Python that this directory should be treated as a regular package. This allows Python to set up the __path__ attribute for the package, which is essential for package introspection tools like pkgutil.walk_packages to correctly locate and list submodules and subpackages.

How This Fails in Real Systems

A deployment script packaged an enterprise system using PyInstaller. Because the subfolders lacked __init__.py files, the packager failed to identify them as static dependencies, leaving them out of the generated runtime build. This caused immediate ModuleNotFoundError crashes upon server startup, taking 6 hours to trace back to PEP 420 dynamic discovery issues.

Key Takeaway

Always place __init__.py files inside your code directories to ensure they are parsed as regular packages with fully resolvable import paths.

Common mistake: Developers assume that any directory containing Python files automatically becomes a package discoverable by tools like pkgutil or import statements, overlooking the explicit role of __init__.py in defining a regular package.