Fix ImportError in Python

Error Reference

ImportError: cannot import name ...

The module exists, but the symbol you're importing doesn't. Track it down with this checklist.

ImportError vs ModuleNotFoundError

ModuleNotFoundError is a subclass of ImportError, and the split tells you where to look:

ModuleNotFoundError: No module named 'x' — Python couldn't find the module at all. Check installation and environment.
ImportError: cannot import name 'y' from 'x' — the module x was found and loaded, but the name y isn't in it.

import nonexistent_module
# ModuleNotFoundError: No module named 'nonexistent_module'

from math import cubes
# ImportError: cannot import name 'cubes' from 'math'

Because of the subclass relationship, except ImportError: catches both.

Cannot import name

When the module loads but the name is missing, there are three usual suspects:

Typo — from json import load works; from json import laod doesn't. Names are case-sensitive.
Wrong version — the name exists in the version you read the docs for, not the one you installed. Check with pip show package and compare against the changelog.
It was never there — you're importing from the wrong module inside a package (from sklearn import train_test_split fails; it lives in sklearn.model_selection).

Verify what the module actually exports before guessing:

import json
print([name for name in dir(json) if not name.startswith('_')])
# ['JSONDecodeError', 'JSONDecoder', 'JSONEncoder', 'codecs', 'decoder',
#  'detect_encoding', 'dump', 'dumps', 'encoder', 'load', 'loads', 'scanner']

Circular imports

Two modules importing each other at the top level can't both finish loading. A minimal reproduction:

# a.py
import b

def greet():
    return 'hello'

# b.py
from a import greet  # runs while a.py is still half-loaded

print(greet())

Running python b.py fails:

ImportError: cannot import name 'greet' from partially initialized module 'a'
(most likely due to a circular import)

Python starts loading a, hits import b, and pauses there. Loading b immediately asks a for greet — but a is still frozen on its first line, so greet doesn't exist yet.

Three fixes, in order of preference:

Restructure — move the shared function into a third module (common.py) that both import. Cycles usually signal that two modules own a piece of each other's job.
Import the module, not the name — import a then call a.greet() later. The lookup happens at call time, after a has finished loading.
Import inside the function — defers the import until the function runs, when both modules are fully initialized:

# b.py
def announce():
    from a import greet  # resolved at call time, cycle broken
    print(greet())

Frequently Asked Questions

What does "cannot import name X from partially initialized module" mean?

It is the signature of a circular import. Module A started loading, imported B, and B tried to import a name back from A before A finished executing. Break the cycle: move shared code to a third module, import the module instead of the name, or move the import inside the function that needs it.

How do I check what a module actually exports?

dir(module) lists every attribute the loaded module has, which is the ground truth for what you can import from it. If the module defines __all__, that list is what 'from module import *' would bring in — but explicit imports can still reach any name dir() shows.

import csv
print(dir(csv))          # everything importable
print(csv.__all__)       # the module's declared public API

Next up in your learning path

ModuleNotFoundError

Handle missing modules.

Stack traces

Read tracebacks to find which import failed.

Debugging

Module layout

Organize packages cleanly to avoid conflicts.

Background