Python makes it simple to add extra libraries. You run pip install and expect it to work, and most of the time it does.

ModuleNotFoundError: No module named 'xyz'

But sometimes, even after you install a package with pip install xyz, you still get an error saying it can’t find the package. You check again, reinstall, maybe restart your editor, but the problem doesn’t go away. So, what’s going on?

What Triggers the “ModuleNotFoundError” in Python?

There are a few common reasons this occurs:

Package Installed in a Different Environment

You may have installed the package in one environment (e.g., system Python), but you’re running your code in another (like a virtual environment or Jupyter kernel).

Multiple Python Versions on Your System

On systems with both Python 2.x and Python 3.x, or multiple installations of Python 3 (like 3.8 and 3.11), packages may be installed in the wrong version’s site-packages.

Wrong pip Being Used

When you run pip install, it might be referring to a different Python interpreter than the one you’re using to execute the script (python vs python3, pip vs pip3, etc.).

The Package Name is Incorrect

Some Python modules are named differently from the packages that install them. For example, pip install python-dateutil provides a module called dateutil, not python-dateutil.

Step-by-Step Fix: How to Resolve the ModuleNotFoundError

Here’s how to systematically solve this issue:

Step 1: Check Python Version and Pip Linkage

Run the following commands to verify which Python version and pip are being used:

which python
which pip

Or on Windows:

where python
where pip

You can also check the version linked to pip:

pip --version

Make sure pip is installing packages for the same Python interpreter you’re using to run your code.

Step 2: Install the Package for the Correct Python Version

If you are using Python 3, use:

python3 -m pip install package-name

This ensures you’re installing the package specifically for the python3 environment.

Step 3: Check If You’re Inside a Virtual Environment

If you’re using a virtual environment (like with venv or conda), ensure it’s activated:

# For venv
source venv/bin/activate # On macOS/Linux
venv\Scripts\activate # On Windows
# For conda
conda activate myenv

Then reinstall the module:

pip install package-name

Step 4: Verify the Module is Installed

You can check if the module is installed with:

pip list

Or use the following to test import directly:

python -c "import package_name"

If this doesn’t raise an error, the module is correctly installed and available in your environment.

Step 5: Jupyter Notebook/VSCode Users – Check Kernel/Interpreter

In Jupyter:

  • Go to Kernel > Change Kernel and make sure it points to the correct environment.

In VSCode:

  • Press Ctrl + Shift + P → Select “Python: Select Interpreter” → Choose the correct one.

Best Practices to Resolve the ModuleNotFoundError

  • Always use python -m pip install instead of just pip install
  • Use virtual environments to isolate dependencies
  • Confirm the package/module name before importing

Final Words

The ModuleNotFoundError usually means Python can’t find the module in the currently active environment. This often happens because of mismatched installations, virtual environment confusion, or multiple Python versions. By aligning your pip and python usage, confirming the correct interpreter, and managing virtual environments properly, you can resolve this issue with confidenceIf you’re managing complex projects with multiple environments or dependencies, or you just want clean, reliable builds across your team, it might be time to hire Python developers who know how to structure things right from the start.