What this usually means
Python modules execute top-to-bottom when first imported. If module A imports module B, but B (directly or indirectly) tries to import A before A finishes executing, you get a circular dependency. The 'partially initialized' error means Python has created a stub module object for A (with some attributes set) but hasn't completed execution. When B tries to access a name from A that hasn't been defined yet, it fails. This is rarely a Python bug—it's almost always a design issue where modules have tight coupling and overlapping responsibilities.
The first ten minutes — establish facts before touching code.
- 1Run 'python -v your_script.py 2>&1 | grep import' to see the exact import order and spot where the cycle starts
- 2Insert 'import sys; print(list(sys.modules.keys()))' at key points to see what's already loaded
- 3Set the environment variable 'PYTHONDONTWRITEBYTECODE=1' and add temporary print statements at module level to trace execution order
- 4Use 'importlib.util.find_spec' to check if a module is already in sys.modules before importing
- 5Simplify: create a minimal reproduction by removing all code except the imports and the failing line
The specific files, logs, configs, and dashboards that usually own this bug.
- search__init__.py files—they're often the source because they import submodules eagerly
- searchTop-level imports inside functions or methods (late imports hidden in code)
- searchCircular imports through third-party libraries (e.g., plugin systems that import back into your code)
- searchsys.modules dump after the error to see which modules are partially loaded
- searchThe traceback's last few lines—the cycle is usually 2-4 modules deep
Practical causes, not theory. These are the things you will actually find.
- warning__init__.py re-exports classes from submodules, creating a cycle when submodule imports that __init__.py
- warningType hints with forward references that trigger imports at module load time (use 'from __future__ import annotations')
- warningModel relationships in ORMs (SQLAlchemy, Django) where models reference each other in relationships defined at module level
- warningCircular dependency between utility modules and the modules they're meant to help
- warningPlugin or dynamic import patterns where a main module imports plugins that import the main module back
Concrete fix directions. Pick the one that matches your root cause.
- buildMove the import inside the function or method that actually uses it (lazy import)
- buildBreak the cycle by extracting the shared dependency into a third module
- buildUse 'from __future__ import annotations' to defer evaluation of type hints
- buildRestructure __init__.py to avoid re-exporting classes that create cycles (import submodules explicitly instead)
- buildUse 'import module' instead of 'from module import name' to defer name resolution to attribute access
- buildIn ORMs, use string-based references or lazy relationships (e.g., 'back_populates' in SQLAlchemy)
A fix you cannot prove is a guess. Close the loop.
- verifiedRun the application with 'python -v' and confirm the import order no longer shows a cycle
- verifiedWrite a small test that imports all modules in the same order as the real app—should complete without error
- verifiedCheck that all module-level names (classes, functions) are accessible after import
- verifiedRemove the fix temporarily and confirm the error returns to prove the cycle was real
- verifiedRun your test suite with coverage to ensure lazy imports don't break test isolation
Things that make this bug worse or harder to find.
- warningPutting imports inside a function that is called at module level (defeats the purpose)
- warningUsing 'import *'—obscures what is imported and can create hidden cycles
- warningAdding 'sys.path' hacks or monkey-patching sys.modules—these mask the real problem
- warningAssuming the error is always in the module where it's raised; trace the full cycle
- warningMoving imports to the bottom of the file; it doesn't fix the cycle, just changes the timing
Django Model Circular Import Nightmare
Timeline
- 09:15Deployed a new model 'Invoice' with a ForeignKey to 'User' in a separate app
- 09:17CI fails with 'ImportError: cannot import name Invoice from partially initialized module'
- 09:20Checked the traceback: cycle between 'invoices.models' and 'users.models'
- 09:25Dumped sys.modules: 'invoices' is partially loaded, 'users' is waiting for 'invoices'
- 09:35Discovered that 'users/models.py' has 'from invoices.models import Invoice' at module top for a signal
- 09:40Moved the import inside the signal function; test passes locally
- 09:45CI passes; deployed to staging
- 10:00Staging works but Celery tasks fail with the same error—found a second import in tasks.py
- 10:10Applied the same lazy import pattern to Celery tasks; all green.
I pushed a seemingly innocent change: a new Invoice model in the invoices app, with a ForeignKey to User from the users app. The CI pipeline blew up with 'ImportError: cannot import name Invoice from partially initialized module invoices.models'. I've seen this before—circular import. But the traceback only showed invoices and users, a simple two-module cycle.
I dumped sys.modules at the crash point: invoices.models was half-loaded (had some attributes but not all), and users.models was trying to import Invoice. The users/models.py had a top-level import of Invoice for a post_save signal. That was the problem: when Django loaded users.models, it tried to import invoices.models, which tried to import users.models (via the FK), but users wasn't done yet. Classic.
I moved the import inside the signal function. Local tests passed. CI green. But then staging failed again—Celery tasks had the same import. I fixed those too. Lesson: always grep for all occurrences of the import, not just the one in the traceback. And never put model imports at module level in Django apps that have cross-app dependencies.
Root cause
Module-level import of Invoice in users/models.py created a cycle: users.models -> invoices.models -> users.models.
The fix
Moved the import inside the signal function and inside Celery task functions (lazy import).
The lesson
Always check for multiple import sites, not just the one in the traceback. Use 'from __future__ import annotations' for type hints, and keep model imports inside functions when they're not needed at module load.
When Python imports a module, it first checks sys.modules. If not found, it creates a new module object (initially empty), adds it to sys.modules, then executes the module's code. If during execution another module tries to import the first one again, Python finds it in sys.modules but it's only partially initialized. This is the root of all circular import errors.
The key insight: 'import module' is safe even in a cycle because attribute access is deferred. But 'from module import name' tries to resolve the name immediately, which fails if the module hasn't defined it yet. That's why 'from x import y' breaks more often than 'import x'.
Insert this code at strategic points to see what's loaded: 'import sys; print([k for k in sys.modules.keys() if 'yourproject' in k])'. Run with 'python -v' to get a timestamped log of every import. The cycle will show as a repeated pattern of the same modules being imported.
For more advanced debugging, use 'importlib.util.find_spec' to check if a module exists without triggering import. Or temporarily wrap the import in a try/except that prints the stack trace to see the full cycle.
Lazy imports (moving import inside functions) are the quickest fix but can hide design issues. They also add a tiny runtime overhead. Use them sparingly—prefer restructuring when the cycle is a symptom of poor separation of concerns.
Extracting shared code into a common module is the cleaner fix. For example, if module A and B both need a utility function, put it in 'utils.py'. If models from two apps reference each other, consider an intermediate association model or using Django's 'swappable' dependencies.
Python 3.7+ allows 'from __future__ import annotations' to make all annotations strings (PEP 563). This defers evaluation, eliminating import cycles caused by type hints. Always add this import at the top of modules that have cross-references.
If you can't use future annotations, use string literals in type hints: 'def foo() -> "Bar": pass'. This works with most type checkers and avoids import-time evaluation.
Django: model imports in signals, admin, or serializers often cause cycles. Use 'from django.apps import apps' and 'apps.get_model('app_label', 'ModelName')' for lazy model loading. In Django 3.1+, use 'settings.AUTH_USER_MODEL' as a string for ForeignKey.
SQLAlchemy: relationships defined with 'back_populates' can cause cycles if the related model is imported at module level. Use string names for 'secondary' and 'order_by' arguments. For 'relationship()', pass the class as a string: 'relationship("OtherModel")'.
Frequently asked questions
Why does 'from x import y' fail but 'import x' work in a circular import?
'import x' only adds a reference to the module object in the namespace; it doesn't resolve any names. 'from x import y' tries to get the attribute 'y' from module 'x' immediately. If 'x' hasn't finished executing, 'y' may not exist yet, raising ImportError. Use 'import x' and then 'x.y' when you suspect a cycle.
Can circular imports ever be safe?
Yes, if the cycle is broken by using 'import module' (not 'from') and accessing names only after all modules are fully loaded. But it's fragile. A change in import order or a new import can break it. Safer to restructure or use lazy imports.
How do I find the exact import order that causes the cycle?
Run your script with 'python -v 2>&1 | grep import'. This prints every import as it happens. Look for a repeated pattern like 'import A' then 'import B' then 'import A' again. You can also add temporary print statements at the top of each module.
Does '__init__.py' always cause circular imports?
Not always, but it's a common source because __init__.py often re-exports names from submodules. If submodule A imports from submodule B, and B's __init__.py imports from A, you have a cycle. Keep __init__.py minimal: import submodules explicitly, don't re-export unless necessary.