How to Fix: ModuleNotFoundError: No module named ‘…’

Quick Fix

Most of the time this error means the package simply is not installed in the Python environment you are actually running.

1. Install the missing package with python -m pip install module_name (replace module_name with the exact name from the error, but note some packages install under a different name than they import — e.g. install opencv-python but import cv2).
2. Check you are using the right Python/environment. Run python -c "import sys; print(sys.executable)" and make sure it points to the same Python (or activated virtual environment) that you used to install the package.
3. If you use a virtual environment, activate it first before installing or running: source venv/bin/activate (Mac/Linux) or venvScriptsactivate (Windows).

Step-by-Step Guide

What this error means

ModuleNotFoundError: No module named '...' is raised by Python when it cannot locate a module or package you tried to import. Python searches for the specified module in its installed packages and project directories, and if it cannot find the module, it raises a ModuleNotFoundError. The fix depends entirely on why Python can't see it, so work through the causes below in order.

Cause 1: The package is not installed at all

This is the single most common reason for the error.

1. Confirm it is missing. Run pip show module_name in your terminal. If it prints 'not found', the package genuinely is not installed.
2. Install it with pip. Run python -m pip install module_name (use python3 or pip3 on Mac/Linux if 'python' points to Python 2). Using python -m pip instead of a bare pip command guarantees the package installs for the exact interpreter you will run the script with.
3. Watch for name mismatches. Sometimes the package name differs from the import name, for example pip install Pillow but import PIL, pip install opencv-python but import cv2, pip install scikit-learn but import sklearn, pip install PyYAML but import yaml, and pip install beautifulsoup4 but import bs4.

Cause 2: You installed the package in the wrong Python environment

This is the second most common cause, especially with virtual environments, conda, or multiple Python versions installed side by side.

1. Check which Python and pip you are actually using. Run which python and which pip on Mac/Linux, or where python on Windows. Verify installation in Python by checking sys.executable to see which Python is being used — a frequent issue is having multiple Python installations and installing packages in the wrong one.
2. Activate your virtual environment before installing or running anything. On Windows use .venvScriptsactivate; on Mac/Linux use source venv/bin/activate. You can check whether a virtual environment is active by running echo $VIRTUAL_ENV, which should print the venv path if active.
3. Reinstall inside the active environment. Once activated, run pip install module_name again (or pip install -r requirements.txt if you have a requirements file) so the package lands inside the venv rather than globally.
4. If using an IDE (VS Code, PyCharm, etc.), make sure it points to the same interpreter. In VS Code, open the command palette and select 'Python: Select Interpreter', then choose the interpreter matching your active virtual environment.
5. If you have multiple Python versions, be explicit. If using Python 3.10, install with python3.10 -m pip install module_name to make sure the package goes to the version you actually run.

Cause 3: Typo or wrong casing in the import statement

1. Re-check the spelling. Python is case-sensitive, so a slight difference in the module name, like typos or incorrect capitalization, will result in a 'No Module Named' error.
2. Compare against the official package documentation or PyPI page to confirm the exact import name.

Cause 4: Your own project files/folders are not on Python's path

This happens with custom local modules and multi-folder projects, not third-party packages.

1. Check your folder structure. In Python 3.3+, __init__.py is not strictly required for a package, but its absence can still cause issues in some setups — make sure each package folder that should be importable has one.
2. Run the script from the correct working directory (usually the project root), since Python resolves relative imports based on where you launch it from.
3. Add the project root to PYTHONPATH if needed. On Mac/Linux: export PYTHONPATH="${PYTHONPATH}:/path/to/project". On Windows (PowerShell): $env:PYTHONPATH += ";C:pathtoproject".
4. Install your own package in editable mode for development with pip install -e . if you have a setup.py or pyproject.toml, so it's importable from anywhere without path hacks.

Cause 5: A local file is shadowing a real module

1. Check for filename collisions. A file in your own project named the same as a standard library module or the package you're importing (e.g. random.py, string.py, email.py, test.py) will be imported instead of the real one and can cause confusing errors.
2. Rename the conflicting file and delete any leftover .pyc files or __pycache__ folders, then try again.

Cause 6: pip itself is broken (rare)

1. Symptom: the error names 'pip' itself, e.g. ModuleNotFoundError: No module named 'pip', often after an OS or Python upgrade.
2. Fix it by reinstalling pip. Run python -m ensurepip --upgrade, or download and run get-pip.py from the official pip installation page.

When to seek more specific help

1. If the module is part of a large framework (Django, TensorFlow, PyTorch, etc.) with C-extension or GPU dependencies, check that project's official installation docs — version mismatches between the library and your Python/CUDA version are a common, package-specific cause.
2. If you're inside Docker, Jupyter, or a cloud notebook (Colab, Databricks), install packages using that platform's specific method (e.g. a Dockerfile RUN pip install line, or a notebook cell starting with !pip install), since a normal terminal install won't reach that isolated environment.
3. If none of the above resolves it, delete and recreate your virtual environment from scratch, then reinstall everything from a known-good requirements.txt — this clears out any corrupted or conflicting install state.