Master Python Relative Imports: Implicit vs Explicit and Best Practices

From the directory tree we can see that mypackage is a package containing two sub‑modules a and b, each with its own __init__.py and a single module file ( bar.py in a, foo.py in b).

$ tree
mypackage
|____ __init__.py
|____ a
|     |____ __init__.py
|     |____ bar.py
|____ b
      |____ __init__.py
      |____ foo.py

The most basic import method shown is the implicit relative import, where the import statement does not specify the origin module and defaults to the current module’s location.

In [1]: import mypackage
In [2]: import mypackage.a
In [3]: import mypackage.a.bar

Explicit relative imports use leading dots to indicate the current ( .), parent ( ..), or higher‑level modules ( ...). Examples:

In [4]: from mypackage import a
In [5]: from mypackage.b import foo
In [6]: from mypackage.a.bar import BAR
In [1]: from ..b.foo import FOO

Relative imports are especially useful in large projects with deep module hierarchies, improving maintainability and keeping import statements concise. They are also handy during early development when package names or locations may change. Generally, if a module hierarchy exceeds three levels, explicit relative imports are recommended.

To disable implicit relative imports, add from __future__ import absolute_import at the top of __init__.py. This forces imports to resolve to the standard library first, preventing accidental name clashes.

# __init__.py
from __future__ import absolute_import
from os import a  # will try to import from the real stdlib os module

When the absolute import is enabled, attempting to import a from a locally defined os.py will raise an ImportError because the standard library os module is found first.

Using from xxx import * is discouraged because it imports everything indiscriminately. Instead, define an __all__ list in __init__.py (or any module) to explicitly expose only the intended symbols.

# mymodule.py
__all__ = ['a']
a = 1
b = 2

In [1]: from mymodule import *
In [2]: a  # works, value 1
In [3]: b  # NameError, not exported

A real‑world example from Flask shows how the package’s __init__.py can re‑export frequently used objects, providing a clean entry point for users.

# flask/__init__.py (excerpt)
from .app import Flask, Request, Response
from .config import Config
from .templating import render_template, render_template_string
from . import json
jsonify = json.jsonify

Overall, the article demonstrates the mechanics of Python’s import system, the distinction between implicit and explicit relative imports, when to apply each strategy, how to avoid common pitfalls, and how to design package interfaces for better maintainability.