Executing a Python script or starting an application in Linux only to be halted by the traceback: ‘ModuleNotFoundError: No module named [module_name]’ halts software development and deployment scripts. In Python runtime architecture, whenever an import statement is executed, the Python interpreter queries the sys.path search path list—including the current working directory, PYTHONPATH environment variables, and system site-packages directories—to locate the target module. When a package is installed in a different Python version, a virtual environment is unactivated, or file permissions prevent reading, the interpreter aborts execution.
Why Does Python Throw ModuleNotFoundError in Linux?
The error indicates the interpreter exhausted all directories in sys.path without finding the requested library:
- Unactivated Virtual Environment: The library was installed inside a virtual environment (
venv), but the script is running against the global system Python interpreter. - Multiple Python Versions Installed: The package was installed using
pipfor Python 3.10, while the script is executed using Python 3.12. - Missing Package Installation: The required library has not been installed on the host system.
- Missing __init__.py in Local Packages: Attempting to import local directory packages without proper package markers.
- Debian/Ubuntu Externally-Managed-Environment Restriction (PEP 668): System Python preventing direct
pip installoutside isolated virtual environments.
Step 1: Verify Which Python Interpreter Is Running
Confirm the exact Python binary and pip executable your shell is calling.
- Check the active Python binary:
which python3 python3 --version - Check the pip binary:
which pip pip --version - Ensure that
pippoints to the exact same Python version directory aspython3.
Step 2: Install Packages via the Correct Python Binary
Using python3 -m pip guarantees that the library installs directly into the active Python environment’s site-packages.
- Never call
pip installdirectly if multiple Python versions exist. Instead, execute:
(Replacepython3 -m pip install <module_name><module_name>with your package, e.g.requests,pandas, ornumpy). - If on Ubuntu 24.04+ or Debian 12 (PEP 668 managed environment), install the system package via APT:
sudo apt install python3-<module_name> # E.g. sudo apt install python3-requests
Step 3: Activate Your Virtual Environment
If your project utilizes a virtual environment, ensure it is actively sourced in your shell session.
- Navigate to your project root directory.
- Activate the virtual environment:
source venv/bin/activate # Or source .venv/bin/activate - Verify that your terminal prompt shows the virtual environment prefix:
(venv) user@host:~$. - Re-run your script inside the activated shell.
Step 4: Inspect sys.path Inside the Script
Check the exact directory search paths Python evaluates during runtime.
- Run an inline Python command to print
sys.path:python3 -c "import sys; print('\n'.join(sys.path))" - Confirm whether the directory containing your package is listed.
- To add a custom module directory temporarily, export
PYTHONPATH:export PYTHONPATH="${PYTHONPATH}:/path/to/your/modules"
Step 5: Verify Local Package Structure (__init__.py)
If importing custom modules from neighbouring project folders, ensure directory packaging is intact.
- Ensure an
__init__.pyfile exists inside each sub-folder you wish to import as a package:touch my_package/__init__.py - Ensure file read permissions allow standard user execution:
chmod -R 755 my_package/
Executing pip via python3 -m pip, activating project virtual environments, setting PYTHONPATH, and verifying sys.path directories permanently resolves ModuleNotFoundError in Linux.