How to Fix Python ModuleNotFoundError inside Virtualenv / Venv

The exception ModuleNotFoundError: No module named 'module_name' is one of the most frequent errors in Python development. It occurs when Python attempts to import a package that is missing from the search path (sys.path) of the active Python interpreter.

Step-by-Step Solution

1. 1

   Step 1: Verify Virtual Environment Activation

   Ensure your virtual environment is activated and check which Python binary is currently active:

   BASH Copy

   # On Linux / macOS: activate virtualenv
   source venv/bin/activate
   
   # On Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   
   # Verify the active Python binary path
   which python    # Linux/macOS
   where python    # Windows
   

   (The path output should point to your project's venv/bin/python directory, not system /usr/bin/python).

2. 2

   Step 2: Install Packages via Module Syntax

   To guarantee that packages are installed into the virtual environment rather than system-wide Python, use python -m pip:

   BASH Copy

   python -m pip install module_name
   

   Verify that the module is installed in the active environment:

   BASH Copy

   python -m pip list
   

3. 3

   Step 3: Select the Correct Python Interpreter in Your IDE

   If the script runs in the terminal but fails inside your code editor (e.g., VS Code or PyCharm):

   • VS Code: Press Ctrl + Shift + P (or Cmd + Shift + P on macOS), search for Python: Select Interpreter, and choose the interpreter inside venv/bin/python.
   • PyCharm: Navigate to Settings > Project > Python Interpreter and assign your project's virtual environment path.