This error indicates that your Python code has a circular dependency—when two or more modules depend on each other directly or indirectly through import statements. This results in an import loop that Python cannot resolve during the execution of the program.
A circular import occurs when:
This creates a cycle where Python tries to load both modules simultaneously, but neither can complete because each is waiting for the other to finish importing.
# file: a.py from b import func_b def func_a(): print("Function A") # file: b.py from a import func_a def func_b(): print("Function B")
Running either file results in an import error because of the circular reference.
Scenario | Resolution |
---|---|
You’re unsure which file is causing the loop | Trace the import tree manually or use Python tools like trace or importlib.util for debugging. |
You need functions from both modules | Use lazy importing (inside functions) or create a shared utility module to hold common logic. |
You're working with a large codebase | Consider refactoring into a package structure with clearly defined responsibilities to minimize tight coupling. |
pylint
, which often catch structural issues in module imports.Last updated: 26 Jun 2025