Python 'ImportError: cannot import name 'X' from partially initialized module 'Y' (most likely due to a circular import)': how do I fix it?

Cause: two or more modules import each other at top level. Python adds a module to sys.modules before running its code, so when module A imports B and B then does from A import name, A is only partly executed and the name it wants has not been defined yet. The error names the partially initialized module and often the file path. A common variant is a script that shares its name with a module it imports (for example your own random.py or a file named like the library you use), which also produces a partially initialized module message. Fix (best first): 1. Restructure: move the shared classes, constants or functions that both modules need into a third module that imports neither, so the dependency runs one way. 2. Import the module rather than the name, and look the attribute up at call time: write import foo and use foo.thing inside functions instead of from foo import thing at the top. The Python FAQ states that import module is fine in circular situations; the problem is from module import name at import time. 3. Move the import inside the function that uses it (a lazy import). Importing repeatedly is cheap because modules are cached in sys.modules. 4. For type hints only, use from __future__ import annotations or the typing.TYPE_CHECKING guard so the import runs only for type checkers: if TYPE_CHECKING: from foo import Thing, and quote the annotation or rely on postponed evaluation. 5. For the name-shadowing variant, rename your file (and delete stale __pycache__ entries) so it does not collide with a standard library or installed package name. 6. Do not try to make it work by reordering imports and hoping; that is fragile. Verify: python -c "import yourpackage.module_a; import yourpackage.module_b" succeeds in either order, and your test suite imports each module in isolation. Sources: https://docs.python.org/3/faq/programming.html#how-can-i-have-modules-that-mutually-import-each-other https://docs.python.org/3/reference/import.html