ModuleNotFoundError
This error occurs when Python cannot locate the specified module package inside your active environment search paths.
Usually happens because:
- ☑ The third-party package has not been installed in the environment
- ☑ Active virtual environment (venv) is not activated in the shell terminal
- ☑ Spelling typo or capitalization discrepancy in import string
🔍 Quick Checklist:
What is ModuleNotFoundError?
The 'ModuleNotFoundError' is a subclass of 'ImportError' introduced in Python 3.6. It indicates that the Python interpreter failed to locate an external library or a local module referenced in an 'import' statement. This typically happens because the package has not been installed inside the active virtual environment, the module folder lacks an '__init__.py' file (for older Python compatibility), or the folder is missing from Python's search path ('sys.path').
Common Causes
- Missing package installation: Trying to import a third-party library (like 'requests' or 'numpy') that has not been installed using pip.
- Active virtual environment mismatch: Installing the package globally but running the code inside an isolated virtual environment (venv) where it is missing.
- Spelling typo or casing mismatch: Mismatch in capitalization or spelling of the module name.
| Cause | Frequency |
|---|---|
| Package has not been installed using pip | ⭐⭐⭐⭐⭐ |
| Virtual environment mismatch (stale shell environment) | ⭐⭐⭐⭐ |
| Folder path omitted from sys.path listing | ⭐⭐⭐ |
Common Mistakes
- Installing package using global system commands (`sudo apt install python3-requests`) when working within local virtual environments (`venv`), which will not propagate dependencies inside the environment.
- Using spelling name matches that differ from installation naming (e.g. running `pip install PyYAML` but writing `import yaml` in scripts).
How to Fix
Python Operations & Verification
Ensure your virtual environment is active, then download the missing package using pip.
# 1. Activate your virtual environment (Linux/macOS)
$ source venv/bin/activate
# 2. Install the package inside the active environment
(venv) $ pip install requests
# 3. Launch python script successfully
(venv) $ python script.pyPlatform Specific Fixes
Verify installed packages inside the system python path.
python3 -m pip list | grep -i requestsBest Practices
- Manage repository package configurations inside a `requirements.txt` file and execute installs using `pip install -r requirements.txt`.
- Always check that your shell prompt shows the active environment marker `(venv)` before editing packages.
Frequently Asked Questions (FAQ)
Q: What is ModuleNotFoundError?
It is a subclass of ImportError raised when a module cannot be found during import resolution.
Q: Why does it fail when I already installed the package?
You likely installed the package globally or in a different virtual environment. Make sure you activate your current virtual environment before installing packages.
Q: How do I import a local file from a parent folder?
Add the folder path to the environment variable PYTHONPATH, or append it to sys.path in your script: 'import sys; sys.path.append("/path/to/folder")'.
Q: Why is the package name different from the import name?
Some packages have different installation names compared to their import names. For example, you run 'pip install beautifulsoup4' but import it using 'import bs4'.