How to Fix: ImportError: circular import (A Deep Dive)

When working on a Python project, developers often encounter a frustrating logic error. You might identify this crash as an ImportError circular import. This specific issue represents a structural flaw in your code’s architecture. Essentially, it means that File A attempts to import File B, while File B simultaneously tries to load File A. Because both files wait on each other, the program gets stuck in an infinite loop and eventually crashes.

# Fix 1 — Refactor: move shared functions into a third module (utils.py)
# utils.py — imports nothing
def a_func(): print("Hello from A")
def b_func(): print("Hello from B")

# a.py — imports from utils only
from utils import b_func

# b.py — imports from utils only
from utils import a_func

# Fix 2 — Local import: delay the import inside the function body
def b_func():
    from a import a_func  # Only runs when b_func() is called
    a_func()

The Cause Behind an ImportError circular import

Let us imagine you have two separate Python files that rely on one another. This common scenario easily leads to trouble.

a.py:

from b import b_func # <-- Python loads 'b.py'

def a_func():
    print("Hello from A")

b_func()

b.py:

from a import a_func # <-- Python loads 'a.py' (which is already loading!)

def b_func():
    print("Hello from B")

The Crash Sequence:

Here is exactly what happens behind the scenes during the failure:

1. First, you run the command python a.py.
2. The interpreter starts reading a.py and encounters the line from b import b_func.
3. Next, the system pauses execution of a.py and jumps directly into b.py to locate b_func.
4. As it reads b.py, the interpreter hits the line from a import a_func.
5. Finally, the program jumps back to a.py. However, a.py remains paused, and the script has not defined a_func yet!
6. This sequence triggers the dreaded message: ImportError: cannot import name 'a_func' from partially initialized module 'a'. This represents a classic ImportError circular import.

The Fix 1: Refactor (The Correct Way)

Encountering this error usually means your code modules are too tightly coupled. The best, most robust solution is to break the dependency chain completely. You achieve this by creating a third module (for example, utils.py) that holds the functions or classes required by both original files.

utils.py:

# This file imports nothing!
def a_func():
    print("Hello from A")
    
def b_func():
    print("Hello from B")

a.py:

from utils import b_func
b_func()

b.py:

from utils import a_func
a_func()

Now, a and b don’t know about each other. They only know about utils. The circle is broken.

The Fix 2: Local Import (The “Hack”)

You can also “delay” the import by moving it inside the function. This is generally bad practice, but sometimes necessary.

a.py:

from b import b_func
def a_func():
    print("Hello from A")
b_func()

b.py:

def b_func():
    # The import only happens when b_func is CALLED
    # By then, 'a.py' will be fully loaded.
    from a import a_func 
    print("Hello from B")
    a_func()

This delayed approach works because the interpreter only evaluates the import statement when b_func explicitly runs, giving a.py enough time to fully load. However, keeping your imports at the top of the file remains the Pythonic standard. We highly recommend utilizing the refactoring method (Fix 1) to keep your project clean, organized, and bug-free.

What This Error Exposes About Python’s Module Loading Architecture

ImportError: cannot import name 'a_func' from partially initialized module 'a' is Python’s module registry exposing a race condition in your dependency graph. The interpreter tracks every module it loads in sys.modules. The moment it starts executing a.py, it registers a partial entry for a. When b.py then requests a_func from that same entry, the function does not exist yet — the file never finished executing. Python returns the incomplete module object and the name lookup fails immediately.

The root cause is always tight coupling between modules. Two files that need each other’s functions are doing too much — they share responsibilities that belong in a dedicated shared module. The utils.py refactor breaks the cycle by introducing a dependency direction: both a and b point inward to utils, and utils points to nothing. That unidirectional graph is the architectural target for every well-structured Python project.

The local import workaround functions because sys.modules caches completed modules — by the time b_func() runs and triggers from a import a_func, a.py has fully loaded and a_func exists in the registry. It resolves the crash without restructuring the codebase, but it buries import logic inside function bodies where no developer expects to find it. Reserve that pattern for legacy codebases where refactoring carries too high a risk, and treat every local import as a technical debt marker that needs a utils extraction on the next refactor cycle.