Introduction

These errors often mean Python started importing a module, got interrupted by another import that pointed back to the first module, and then found the first module only half-initialized. That is a circular import. The fix is usually not a clever import trick, but a cleaner module dependency structure.

What a Circular Import Looks Like

Suppose you have two files:

1# a.py
2from b import helper
3
4def run():
5    return helper()

1# b.py
2from a import run
3
4def helper():
5    return "ok"

When Python imports a, it begins executing a.py. That import immediately asks for b, so Python starts executing b.py. But b.py imports a again, and now Python sees a only in its partially initialized state.

That is why you get errors such as:

• 'ImportError: cannot import name ...'
• 'AttributeError: partially initialized module ...'

The name may exist eventually, but not yet at the time the cycle occurs.

Why the Error Message Can Be Confusing

The failing name is often not the real problem. You may think:

• the function name is wrong
• the class does not exist
• the package path is broken

But the real issue is timing. The symbol is unavailable because the module never finished initializing before the reverse import asked for it.

That is why the phrase “most likely due to a circular import” is so useful. It points to import order and dependency structure rather than to a missing definition.

The Best Fix: Remove the Cycle

The cleanest solution is to move the shared dependency into a third module.

Bad structure:

a.py <-> b.py

Better structure:

a.py -> common.py <- b.py

Example:

# common.py
def helper():
    return "ok"

1# a.py
2from common import helper
3
4def run():
5    return helper()

1# b.py
2from common import helper
3
4def other():
5    return helper()

This is the most maintainable fix because it aligns the code with the dependency graph you actually want.

A Temporary Workaround: Local Import

If you cannot refactor immediately, moving the import inside a function can break the cycle.

1# a.py
2def run():
3    from b import helper
4    return helper()

This works because the import happens later, after module initialization time.

It is a valid tool, but it should be used carefully. Local imports solve timing problems, not architecture problems. If the modules genuinely have the wrong responsibilities, the cycle will likely reappear elsewhere.

Another Common Cause: Name Shadowing

Not every “cannot import name” error is a circular import. A file can accidentally shadow a standard library or third-party module.

For example, if your project contains:

random.py

and somewhere else you write:

import random

Python may import your local random.py instead of the standard library module. That can produce very similar symptoms, especially if your local file then imports something that depends on the real module.

So always check for filename collisions before assuming the cycle is the only issue.

Type Hints Can Create Hidden Cycles

Sometimes imports exist only for annotations. In that case, use postponed evaluation or TYPE_CHECKING.

1from __future__ import annotations
2from typing import TYPE_CHECKING
3
4if TYPE_CHECKING:
5    from service import Service
6
7class User:
8    def attach(self, service: Service) -> None:
9        self.service = service

This avoids importing Service at runtime just to satisfy a type hint.

That is a very common fix in larger Python codebases.

How to Debug the Cycle

A practical debugging process is:

1. Read the full traceback carefully.
2. Identify which file import started the chain.
3. Look for the point where module A imports B and B imports A.
4. Decide whether the shared code belongs in a third module.

For a quick sanity check, add small prints:

print("loading a")

inside the modules temporarily. The import order often becomes obvious immediately.

What Not to Do

Do not fix every circular import by scattering local imports everywhere without understanding the dependency graph. That may unblock one import path while making the project harder to reason about later.

Also avoid huge “utility” modules that collect unrelated code just to break cycles. The right extracted module should represent a real shared responsibility.

Common Pitfalls

One common mistake is treating the missing name as the primary bug instead of asking why the module was only partially initialized.

Another issue is importing modules for type hints at runtime when TYPE_CHECKING or postponed annotations would avoid the cycle.

Developers also sometimes create cycles by placing business logic, data models, and application startup code in modules that import each other too freely.

Finally, check for shadowing. A local file named like a standard or third-party module can mimic circular-import symptoms and waste debugging time.

Summary

• A circular import happens when modules depend on each other during initialization.
• The best fix is usually to refactor shared code into a third module.
• Local imports can break the cycle temporarily, but they are not always the cleanest design.
• 'TYPE_CHECKING and postponed annotations help when type hints create import cycles.'
• Always rule out module shadowing before assuming the issue is only a circular dependency.