Module Import

A Python module import is the mechanism that locates, initializes, and binds external Python code (modules or packages) into the current namespace. When an import statement is executed, Python resolves the target module, executes its top-level code to populate its namespace, and creates a reference to that module or its specific attributes in the importing scope.

The Import Resolution Process

When an import statement is invoked, the Python interpreter executes a strict sequence of operations governed by the import system’s finder and loader protocol:

1. Cache Lookup (sys.modules): Python first inspects sys.modules, a dictionary caching all previously imported modules. If the module exists here, Python immediately binds the cached module object to the local namespace, bypassing the rest of the process. A critical detail regarding circular imports is that a module is added to sys.modules before its top-level code finishes executing. Consequently, the cached module object returned during a circular import may be partially initialized.
2. Meta Path Finders (sys.meta_path): If the module is not cached, Python delegates the search to a list of finder objects defined in sys.meta_path. Python iterates through these finders until one successfully locates the module. The standard finders include:
   • BuiltinImporter: Checks if the requested name corresponds to a built-in module compiled directly into the Python interpreter (e.g., sys, time).
   • FrozenImporter: Checks for frozen modules.
   • PathFinder: Searches for the module’s file (e.g., .py, .pyc, or compiled C extensions) across the directory locations listed in sys.path.
3. Loading and Execution: Once a finder locates the module, it returns a ModuleSpec object containing a loader. Under the modern import system (PEP 451, introduced in Python 3.4), the import machinery itself creates the empty module object and registers it in sys.modules. Only after registration does the import machinery call the loader’s exec_module() method to compile (if necessary) and execute the module’s top-level code in an isolated namespace, initializing its attributes, functions, and classes.
4. Namespace Binding: Finally, Python binds the resulting module object, or specific requested attributes, to variables in the local scope where the import statement was called.

Import Syntax and Namespace Binding

The syntax used dictates exactly what is bound to the local namespace.

Standard Import Binds the entire module object to the local namespace under its original name. Accessing its contents requires fully qualified dot notation.

import module_name

Aliased Import Binds the module object to the local namespace under a specified alternate identifier.

import module_name as alias

Specific Attribute Import Extracts specific attributes (functions, classes, or variables) from the module and binds them directly to the local namespace. The module object itself is not bound to the local scope, though it is still loaded into sys.modules.

from module_name import attribute_name, other_attribute

Aliased Attribute Import Binds a specific imported attribute to an alternate identifier in the local namespace.

from module_name import attribute_name as alias

Wildcard Import Binds all public names defined in the target module to the local namespace. Public names are determined by the module’s __all__ list; if __all__ is undefined, it binds all names that do not begin with an underscore (_).

In Python 3, wildcard imports are strictly restricted to the module level. Attempting to execute a wildcard import inside a function or class definition will raise a SyntaxError.

from module_name import *

Absolute vs. Relative Imports

Imports can be categorized by how they resolve the module location relative to the current package structure.

Absolute Imports Specify the fully qualified module name or absolute package hierarchy. Absolute imports are resolved using the finders in sys.meta_path. This means they are first checked against BuiltinImporter and FrozenImporter—resolving built-in and frozen modules entirely independently of sys.path—before falling back to PathFinder, which searches the directory locations listed in sys.path.

from package.subpackage import module

Relative Imports Use dot notation to specify the module’s location relative to the current module’s position in the package hierarchy. These can only be used within packages (using from . import ... syntax). Since Python 3.4 (PEP 451), the import system relies primarily on the __spec__.parent attribute to resolve relative imports. The older __package__ attribute is deprecated for this purpose and raises an ImportWarning in Python 3.10+ if it differs from the spec.

# Import from the current directory
from . import module


# Import from the parent directory
from .. import module


# Import from a sibling package
from ..sibling_package import module

Programmatic Importing

Under the hood, the import keyword invokes the built-in __import__() function. For dynamic imports where the module name is evaluated at runtime as a string, Python provides the importlib standard library, which exposes the internal import mechanics.

import importlib


# Dynamically load a module by its string name
dynamic_module = importlib.import_module("module_name")

Master Python with Deep Grasping Methodology!

Learn More