You just wrote some great code, but when you try to run it the terminal shows a frustrating red message: ImportError. This error is one of the most common obstacles for beginners and experienced developers alike. The Python interpreter is telling you it found difficulties loading a library, package, or specific module you requested. This guide shows you exactly how to fix it quickly.
What is Python ImportError?
ImportError occurs when Python can find the file or module you want to import but fails to load a specific part of it. Unlike ModuleNotFoundError (where the file simply does not exist), ImportError suggests something is wrong with the content or how dependencies are being called. According to the official Python documentation, this exception is raised when an import statement fails to load a module successfully.
Main causes
The most frequent causes are a duplicate file name (you created a file with the same name as a standard library, for example random.py), circular imports (module A imports module B which imports module A before finishing initialization), an incomplete module (the file you are importing does not contain the function or class you requested), or a Python version compatibility issue.
Fix 1: Check your file names
This is the most common mistake. If you saved your script as math.py and wrote import math, Python tries to import your own file instead of the standard library. Rename your file to something unique like my_math_test.py and delete any __pycache__ folders or .pyc files created in the project directory.
Fix 2: Identify circular imports
If user.py imports order.py and order.py imports user.py, a loading loop is created. The solution is to move the imports inside specific Python functions, or reorganize the logic so one module does not depend directly on the other at the global level.
Fix 3: Catch the exact error with try-except
try:
from my_library import my_function
except ImportError as e:
print(f"Import error: {e}")ImportError vs ModuleNotFoundError
Since Python 3.6, ModuleNotFoundError is a subclass of ImportError. In practice: if Python cannot find the package at all on your system, it raises ModuleNotFoundError. If it finds the file but cannot extract what you asked for (like a specific function), it raises ImportError. Using a Python virtual environment eliminates most of these environment-related issues.
Diagnostic script
Run this when you cannot figure out why a module is not being found. It lists every location your Python interpreter is searching:
import sys
import os
def diagnose_import(module_name):
print(f"--- Diagnostics for: {module_name} ---")
print(f"Python version: {sys.version}")
print("nSearch paths (sys.path):")
for path in sys.path:
print(f" > {path}")
try:
module = __import__(module_name)
print(f"nSuccess! Module loaded from: {module.__file__}")
except ImportError as e:
print(f"nFailure detected: {e}")
print("nCurrent working directory:")
print(os.getcwd())
if __name__ == "__main__":
diagnose_import('math')Best practices to prevent ImportErrors
Follow PEP8 naming conventions — avoid generic file names that collide with Python’s built-in modules. Use absolute imports (from my_project.module import function) instead of confusing relative paths. Keep an up-to-date requirements.txt with all project dependencies. Use a virtual environment for every project to isolate package installations.
Frequently Asked Questions
What does “cannot import name” mean?
Python found the module file but cannot find the specific function, class, or variable you tried to import inside it. Check for spelling errors or whether the name actually exists in that version of the library.
How do I fix a circular import?
The best approach is to move the shared dependencies into a third file, or perform the import inside a function so it only runs when that function is called.
Why does Python say a module doesn’t exist right after I installed it?
You likely installed the module in one Python version or virtual environment but are running the script in another. Check which interpreter your terminal or VS Code is currently using.
What is sys.path?
A list of strings that determines where the Python interpreter searches for modules. You can inspect it by importing sys and printing sys.path.
What if the error persists after renaming the file?
Clean up Python’s temporary files. Delete all __pycache__ folders and any .pyc files in your project directory — Python may still be using the old cached version.
