Star Import

A star import (wildcard import) is an import statement that binds all public names from a specified module directly into the current local namespace. This mechanism allows the importing module to access the target module’s functions, classes, and variables without qualifying them with the module’s namespace prefix.

from module_name import *

Name Resolution Mechanics

When the Python interpreter executes a star import, it determines which names to bind to the current namespace based on the presence of the __all__ dunder attribute in the target module.

1. With __all__ defined: If the target module defines a list or tuple named __all__, the star import will strictly bind only the names specified as strings within that sequence.

# target_module.py
__all__ = ['active_connection', 'connect']

def connect(): pass
def disconnect(): pass
active_connection = True

# main.py
from target_module import *

connect()                # Resolves successfully
print(active_connection) # Resolves successfully
disconnect()             # NameError: name 'disconnect' is not defined

2. Without __all__ defined: If __all__ is not defined, the interpreter falls back to a default behavior: it imports all names defined in the target module’s global namespace, excluding any names that begin with a single underscore (_).

# target_module.py
def public_function(): pass
def _internal_function(): pass

# main.py
from target_module import *

public_function()    # Resolves successfully
_internal_function() # NameError: name '_internal_function' is not defined

Namespace Shadowing

Star imports directly mutate the globals() dictionary of the importing module. If a name imported via the wildcard matches a name already defined in the current namespace, the existing reference is silently overwritten.

# external_lib.py
def process_data():
    return "External implementation"

# main.py
def process_data():
    return "Local implementation"

from external_lib import * # Overwrites the local 'process_data' definition

print(process_data()) # Output: External implementation

PEP 8 and Namespace Pollution

PEP 8 strongly discourages the use of wildcard imports in production code. Because star imports inject an unknown set of names into the current environment, they cause severe namespace pollution. This behavior makes it difficult for human readers and static analysis tools (such as linters and type checkers) to determine where names originate, significantly increasing the likelihood of shadowing bugs and maintenance overhead.

Scope Restrictions

In Python 3, star imports are strictly restricted to the module level. Attempting to execute a wildcard import within a function block or class definition will raise a SyntaxError. This restriction exists because Python’s compiler optimizes local variable access at compile time; dynamically injecting unknown names into a local scope via a star import would invalidate these optimizations.

def initialize_system():
    from math import *  # Raises SyntaxError: import * only allowed at module level

Master Python with Deep Grasping Methodology!

Learn More