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

The Difference#

ModuleNotFoundError means Python cannot find the module at all. It is either not installed, not on the Python path, or the name is wrong.

ImportError means Python found the module but cannot import a specific name from it. The module exists, but the thing you are trying to import from it does not.

# 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 there is no output, it is 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 is actually running your code.

Step 4: Package name vs import name#

Some packages have different install names and import names. The most common ones:

Fixing ImportError#

cannot import name 'X' from 'Y' has three causes.

1. Name Does Not Exist in the Module#

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

pip show package-name

Verify the version matches the docs you are reading.

2. Circular Import#

Module A imports from Module B. Module B imports from Module A. Python cannot resolve either one.

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

Move shared code to a third module that neither A nor B imports from.

3. Importing From the Wrong Location#

The name exists in the package but at a different path than you are using. Check the official docs for the correct import path.

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 .

Your project structure should look like this:

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. When they happen deep in a dependency chain where 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.

Open Command Palette with Ctrl+Shift+P and run DebugAI: Analyze Terminal Error.

FAQ#

Q: I installed the package but still get ModuleNotFoundError. What now?

A: Run python -m pip show package-name. If it shows up, but the error persists, your script is running under a different Python than the one where you installed it. Use python -m pip install to guarantee they match.

Q: How do I find out what names a module actually exports?

A: Run python -c "import module_name; print(dir(module_name))" in your terminal. This lists everything the module exposes. If the name you are importing is not in that list, it does not exist in the installed version.

For import errors that happen deep in a dependency chain, paste the full stack trace into DebugAI. It reads your import graph and identifies exactly which import is failing and why.