Solved Error

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 venv\Scripts\activate (Windows).

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.

Step-by-Step Guide

Cause 1: The package is not installed at all

1Confirm it is missing. This is the single most common reason for the error. Run pip show module_name in your terminal. If it prints 'not found', the package genuinely is not installed.
2Install 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.
3Watch 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

1Check which Python and pip you are actually using. This is the second most common cause, especially with virtual environments, conda, or multiple Python versions installed side by side. 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.
2Activate your virtual environment before installing or running anything. On Windows use .venv\Scripts\activate; 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.
3Reinstall 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.
4Select the matching Python interpreter. 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.
5If 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

1Re-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.
2Verify the import name against official documentation. 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

1Check your folder structure. This happens with custom local modules and multi-folder projects, not third-party packages. 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.
2Run the script from the project root directory. Run the script from the correct working directory (usually the project root), since Python resolves relative imports based on where you launch it from.
3Add the project root to PYTHONPATH if needed. On Mac/Linux: export PYTHONPATH="${PYTHONPATH}:/path/to/project". On Windows (PowerShell): $env:PYTHONPATH += ";C:\path\to\project".
4Install 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

1Check 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.
2Rename conflicting files and clear cached bytecode. Rename the conflicting file and delete any leftover .pyc files or __pycache__ folders, then try again.

Cause 6: pip itself is broken (rare)

1Symptom: the error names 'pip' itself, e.g. ModuleNotFoundError: No module named 'pip', often after an OS or Python upgrade.
2Fix 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

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. 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. 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.

Sources:

Heads up: this guide was drafted with AI assistance from the real sources listed below, and structured by our team for clarity. It may not cover every possible cause — if it doesn't fix your issue, let us know and we'll take a closer look. See how we create our fixes.

Was this fix helpful?