Python › Modules & Packaging

How does the module search and caching system handle submodule imports like `import package.subpackage.module`?

Advanced

Answer

Python imports each level of a dotted path in order, caching each intermediate package in sys.modules (e.g., both 'package' and 'package.subpackage' get their own entries), and binds only the top-level name ('package') into the importing namespace -- accessing the submodule requires the full dotted path unless you explicitly import it with `from package.subpackage import module` or alias it.

import package.subpackage.module

# 'package' is bound in the namespace, not 'module' directly
print(package.subpackage.module.some_function())

# To bind 'module' directly:
from package.subpackage import module
module.some_function()

Real-world example A newcomer is confused why `import mypackage.utils` doesn't let them call `utils.helper()` directly -- understanding that only `mypackage` is bound clarifies they need `mypackage.utils.helper()` or a `from...import` instead.

Common follow-ups: Why does `import a.b.c` only bind 'a' in the namespace?;How does `import a.b.c as x` change this binding?

Modules & Packaging;Functions & Scope