HOWTO · Python
How to Fix the ImportError: Cannot Import Name in Python
Diagnose Python's ImportError: cannot import name by checking names, module paths, shadowing, versions, and circular imports, then follow a scoped two-module fix.
On this page
ImportError: cannot import name means Python found a module but could not obtain the requested name from it. A circular import is one possible cause: while Python initializes one module, another module can request a name that has not yet been bound. Misspellings, a different module than expected, shadowing by a local file, an unavailable dependency, or a package/API version mismatch can produce similar symptoms. (demo1_func1; demo2_func1; demo2_func2)
Cause of the ImportError: cannot import name Error in Python
Consider demo1.py and demo2.py. If each file uses from other_module import function at module level, importing either file starts the other import before initialization is complete. In particular, a requested function may not exist yet when the second module asks for it. Python executes module-level statements as part of importing; it does not wait for a function to appear later.
Use the traceback and import context to narrow the cause:
- Read the full traceback to identify the module and name Python could not import.
- Check that the spelling and capitalization match a definition in that module.
- Confirm which file Python resolves: a nearby file named after a standard library module or dependency can shadow the intended module.
- Check that the package is installed in the active environment and that its version provides the API your code expects.
- If the names and paths are correct, trace module-level imports in both directions to find a cycle.
The exact wording after the name varies by Python version and import context, so diagnose from the traceback and module code rather than relying on a fixed suffix.
Fix the ImportError: cannot import name Error in Python
For this two-module case, import the modules and look up their attributes when the functions run. This postpones the name lookup until both modules have finished importing. The following self-contained example creates demo1.py and demo2.py in a temporary directory, then runs demo2.py:
from pathlib import Path
import subprocess
import sys
import tempfile
demo1_source = '''import demo2
def demo1_func1():
print("demo1_func1")
demo2.demo2_func2()
'''
demo2_source = '''import demo1
def demo2_func1():
print("demo2_func1")
demo1.demo1_func1()
def demo2_func2():
print("demo2_func2")
if __name__ == "__main__":
demo2_func1()
'''
with tempfile.TemporaryDirectory() as directory:
Path(directory, "demo1.py").write_text(demo1_source, encoding="utf-8")
Path(directory, "demo2.py").write_text(demo2_source, encoding="utf-8")
result = subprocess.run(
[sys.executable, "demo2.py"],
cwd=directory,
text=True,
capture_output=True,
check=True,
)
print(result.stdout, end="")
demo2_func1
demo1_func1
demo2_func2
The module-import change addresses the illustrated cycle; it is not a universal fix. Depending on the dependency structure, a clearer design may move shared functions into a third module or move an import into a function, with the latter making dependencies less visible at module scope. Flask applications that use Blueprints may also benefit from reviewing this Flask Blueprint guide when organizing application imports.