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:

  1. Read the full traceback to identify the module and name Python could not import.
  2. Check that the spelling and capitalization match a definition in that module.
  3. Confirm which file Python resolves: a nearby file named after a standard library module or dependency can shadow the intended module.
  4. Check that the package is installed in the active environment and that its version provides the API your code expects.
  5. 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.