How to Avoid Circular Imports in Python Code

When a Python program imports modules that mutually depend on each other, the interpreter raises an ImportError because the second module is only partially initialized. The article shows a real traceback from a Docker container where config.py imports crypto_xxx , which in turn imports config again, creating a circular import.

By examining the stack trace, we can see the import chain:

A module → B module

B module → A module

The following minimal example reproduces the problem:

<code># module_a
from module_b import fun_b

def fun_a():
    print('-> fun_a')
    fun_b()

def fun_c():
    print('-> fun_c')

if __name__ == '__main__':
    fun_a()
</code>

<code># module_b
from module_a import fun_c

def fun_b():
    print('-> fun_b')
    fun_c()
</code>

Running python3 module_a.py produces the same ImportError: cannot import name 'fun_b' from partially initialized module 'module_b' .

Solution 1: Import the module instead of the function

<code># module_a
import module_b

def fun_a():
    print('-> fun_a')
    module_b.fun_b()

if __name__ == '__main__':
    fun_a()
</code>

Solution 2: Use lazy (deferred) import inside the function

<code>def fun_a():
    print('-> fun_a')
    from module_b import fun_b
    fun_b()
</code>

Solution 3: Redesign the code structure to separate concerns, place shared utilities in a common module, and avoid mutual imports altogether.

In summary, circular imports arise from poorly planned module dependencies; fixing them involves either importing the whole module, deferring the import until runtime, or refactoring the code to eliminate the circular relationship.