ImportError: cannot import name
This error matches known, documented patterns with reliable solutions.
Quick Fix (Most Common Solution)
- Check module documentation for correct names
- Avoid circular imports
Seeing "ImportError: cannot import name"? This error can be frustrating, but it's usually fixable. It typically affects your development workflow or system. Below you'll find clear, step-by-step solutions to resolve this issue.
What This Error Means
The name you are trying to import does not exist in the specified module.
Frequently documented in developer and vendor support forums.
Not affiliated with browser, OS, or device manufacturers.
New here? Learn why exact error messages matter →
Common Causes
- Circular import issue
- Name was renamed or removed
- Typo in import name
How to Fix
- Check module documentation for correct names
- Avoid circular imports
- Import module then access attribute
Last reviewed: March 2026 How we review solutions
Why This Happens
Python raises ImportError (or its subclass ImportError with a "cannot import name" message) when it finds the module you referenced but cannot locate the specific name you asked for inside that module. This is different from ModuleNotFoundError, which fires when the entire module is missing. The "cannot import name" variant means Python successfully loaded the module file but the class, function, or variable you specified does not exist there. Circular imports are the most common cause in application code: module A imports from module B, and module B imports from module A, creating a loop where one module is only partially initialized when the other tries to read from it. Typos in the imported name are the second most frequent trigger—Python is case-sensitive, so importing "Jsonresponse" instead of "JsonResponse" will fail. Version mismatches also cause this error: a library update may rename, move, or remove a public symbol, breaking imports that worked with the previous version. Understanding the distinction between a missing module and a missing name inside a found module is essential for choosing the right fix.
Quick Diagnostic Checklist
- Read the full error message—it tells you both the module path and the missing name
- Open the source module and search for the exact name (case-sensitive)
- Check for circular imports by tracing the import chain between the two modules
- Verify the installed library version matches the import syntax you are using
- If using __init__.py, confirm the name is explicitly imported or defined there
Circular import causing ImportError with resolution
# --- file: models.py ---
from services import validate_user # <-- imports from services.py
class User:
def save(self):
validate_user(self)
# --- file: services.py ---
from models import User # <-- imports from models.py → CIRCULAR!
def validate_user(user: User):
if not user.name:
raise ValueError("Name required")
# Python loads models.py first, which tries to import from services.py,
# which tries to import User from models.py — but models.py is not
# fully initialized yet, so User does not exist → ImportError
# --- FIX: Move the import inside the function ---
# file: services.py (fixed)
def validate_user(user): # remove type hint or use TYPE_CHECKING
from models import User # lazy import breaks the cycle
if not isinstance(user, User):
raise TypeError("Expected User")
if not user.name:
raise ValueError("Name required")Edge Cases & Unusual Scenarios
Shadowed module name
If you have a file named json.py or requests.py in your project, Python imports your file instead of the standard library or third-party package. Rename your file to avoid shadowing.
Conditional exports in __init__.py
Some packages conditionally export names based on installed extras. For example, importing a GPU-specific class from a machine learning library will fail if the GPU extras are not installed, even though the base package is present.
Need reliable hosting?
DigitalOcean offers simple cloud infrastructure with $200 free credit for new users.
Try DigitalOcean →We may earn a commission from tools recommended in our fixes.
Optional follow-up
Some users ask whether saving fixes for recurring errors would be useful when the same issue appears again.
Was this explanation helpful?
Frequently Asked Questions
What is circular import?
When two modules try to import each other before fully loading.
How do I fix circular imports?
Move import inside function or restructure code.
What is the difference between ImportError and ModuleNotFoundError?
ModuleNotFoundError (a subclass of ImportError since Python 3.6) fires when the entire module is missing. ImportError with "cannot import name" fires when the module exists but the specific name inside it does not.
How do I fix circular imports without restructuring my code?
Move the import inside the function that needs it (lazy import), use typing.TYPE_CHECKING for type hints only, or extract shared code into a third module that both can import without creating a loop.
Can ImportError happen with relative imports?
Yes. Relative imports (from .module import name) follow the same rules. If the name does not exist in the sibling module, or if the package structure is incorrect, you will see ImportError.
Related Resources
Also Known As
- Python exception
- Python traceback
- Python runtime error
- Python crash
Common Search Variations
- "python error fix"
- "python script not working"
- "python traceback what does it mean"
- "how to fix python exception"
- "python crash on startup"
- "python import error solution"
Related Errors
Still Stuck?
Paste a different error message or upload a screenshot to get help instantly.