Module not found - "No module named"

Demystifying 'Module Not Found: No module named' in Python

Encountering 'ModuleNotFoundError' is a common hurdle for Python developers. This article breaks down the root causes, explains Python's module import mechanism, and provides practical solutions to resolve this error efficiently.

The 'ModuleNotFoundError: No module named <module_name>' is one of the most frequent errors Python developers face. It indicates that the Python interpreter cannot locate the module you are trying to import. This can stem from various issues, ranging from simple typos to complex environment configurations. Understanding how Python searches for modules is key to effectively debugging and resolving this error.

Understanding Python's Module Search Path

When you execute an import statement in Python, the interpreter follows a specific sequence to find the requested module. This sequence is defined by the sys.path variable, which is a list of directory names. Python searches these directories in order until it finds the module. If the module is not found in any of these locations, the ModuleNotFoundError is raised.

The sys.path typically includes:

1. The directory containing the input script (or the current directory when running interactively).
2. PYTHONPATH directories (if set).
3. Standard library directories.
4. The site-packages directory for installed third-party libraries.

flowchart TD
    A[Start: import module_name]
    B{Is module_name in sys.modules (already loaded)?}
    B -- Yes --> E[Module found: Use cached version]
    B -- No --> C{Search sys.path directories}
    C --> D{Is module_name found in any sys.path entry?}
    D -- Yes --> F[Module found: Load and execute module]
    D -- No --> G[Error: ModuleNotFoundError]

Python's Module Import Search Flow

Common Causes and Solutions

The 'ModuleNotFoundError' can be triggered by several common scenarios. Identifying the specific cause is the first step towards a resolution. Below are the most frequent reasons and their corresponding solutions.

1. Module Not Installed

This is perhaps the most straightforward cause. If you're trying to import a third-party library (e.g., requests, numpy, pandas), it must be installed in your Python environment. Python's package installer, pip, is used for this purpose.

pip install requests
pip install numpy

Installing Python packages using pip

2. Incorrect File Path or Directory Structure

When importing your own custom modules or modules within the same project, the Python interpreter needs to know where to find them. If the module file is not in the same directory as the script being run, or if the directory is not part of sys.path, Python won't find it.

# project_root/
# ├── main.py
# └── my_package/
#     ├── __init__.py
#     └── my_module.py

# In main.py:
from my_package import my_module

# If my_module.py was directly in project_root:
# import my_module

Example of a correct import statement for a local module

1. Verify Directory Structure

Ensure your project's directory structure is logical. For packages, make sure each directory intended to be a package contains an __init__.py file (even if empty) to signal Python that it's a package.

2. Adjust sys.path (if necessary)

For more complex structures or when running scripts from different locations, you might need to explicitly add the module's parent directory to sys.path. This is often done at the beginning of your script or by setting the PYTHONPATH environment variable.

3. Use Relative Imports

Within a package, use relative imports (e.g., from . import another_module or from .. import parent_module) to reference modules within the same package hierarchy.

3. Virtual Environment Issues

If you're using virtual environments, ensure that the correct environment is activated. If you install a package in one environment but run your script using a different Python interpreter (e.g., the system-wide one), the module won't be found.

# Activate a virtual environment (Linux/macOS)
source venv/bin/activate

# Activate a virtual environment (Windows)
venv\Scripts\activate

# After activation, install packages:
pip install your-package

# Verify the Python interpreter being used
which python # Linux/macOS
where python # Windows

Activating a virtual environment and verifying Python interpreter

4. PYTHONPATH Environment Variable

The PYTHONPATH environment variable can be used to tell Python where to look for modules. While useful, it can also lead to issues if misconfigured or if it points to outdated or incorrect locations.

# Add a directory to PYTHONPATH (Linux/macOS)
export PYTHONPATH="/path/to/your/modules:$PYTHONPATH"

# Add a directory to PYTHONPATH (Windows Command Prompt)
set PYTHONPATH="C:\path\to\your\modules;%PYTHONPATH%"

# Add a directory to PYTHONPATH (Windows PowerShell)
$env:PYTHONPATH="C:\path\to\your\modules;$env:PYTHONPATH"

Setting the PYTHONPATH environment variable

By systematically checking these common causes and applying the suggested solutions, you can effectively troubleshoot and resolve the 'ModuleNotFoundError' in your Python projects.