Python ImportError vs ModuleNotFoundError: What's the Difference and How to Fix Both

The Difference

ModuleNotFoundError — Python can't find the module at all. It's either not installed, not on the Python path, or the name is wrong.

ImportError — Python found the module but can't import a specific name from it. The module exists, but the thing you're trying to import from it doesn't.

# ModuleNotFoundError
import requests  # requests not installed

# ImportError
from datetime import timezone2  # datetime exists, timezone2 doesn't

Both have different causes and different fixes.

Fixing ModuleNotFoundError

Step 1: Check if it's installed

pip show package-name

If no output: not installed. Install it.

pip install package-name

Step 2: Check you're in the right environment

which python
which pip

If they point to different paths, you installed into the wrong environment. Activate your virtualenv:

source venv/bin/activate     # macOS/Linux
venv\Scripts\activate        # Windows

Step 3: Always use python -m pip

python -m pip install requests

This guarantees installation into the Python that's actually running your code.

Step 4: Package name vs import name

Some packages have different install names and import names. Here are the most common ones:

• →Pillow → import as PIL
• →scikit-learn → import as sklearn
• →python-dateutil → import as dateutil
• →opencv-python → import as cv2
• →beautifulsoup4 → import as bs4

Fixing ImportError

cannot import name 'X' from 'Y' — three causes:

1. Name doesn't exist in the module

Check the module's documentation or source. The function may have been renamed, removed, or moved in a newer version.

pip show package-name  # check version

2. Circular import

Module A imports from Module B. Module B imports from Module A. Python can't resolve either one.

ImportError: cannot import name 'X' from partially initialized module 'Y'

Fix: move shared code to a third module that neither imports from the others.

3. You're importing from the wrong location

Check the official docs for the correct import path for each library.

For Local Module ImportErrors

If the error is about your own code:

1. Check you have __init__.py in each package directory

2. Run scripts from the project root, not from inside subdirectories

3. Install your package in editable mode: pip install -e .

my_project/

init.py ← needed for Python to treat this as a package

utils/

init.py ← needed here too

helpers.py

Finding the Root Cause Fast

Import errors usually have clear messages. But when they happen deep in a dependency chain — one module imports another that imports another that fails — the stack trace gets long and confusing.

DebugAI reads your import graph when you index your project. When an import error hits, it already knows your module structure and can tell you exactly which import is failing and why — without you manually tracing the chain.

Ctrl+Shift+P → "DebugAI: Analyze Terminal Error"

Install DebugAI free — Python and JavaScript debugging with full codebase context.