How to Fix ‘ModuleNotFoundError: No module named’ in Python on Linux

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 pip for 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 install outside isolated virtual environments.

Step 1: Verify Which Python Interpreter Is Running

Confirm the exact Python binary and pip executable your shell is calling.

  1. Check the active Python binary:
    which python3
    python3 --version
  2. Check the pip binary:
    which pip
    pip --version
  3. Ensure that pip points to the exact same Python version directory as python3.

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.

  1. Never call pip install directly if multiple Python versions exist. Instead, execute:
    python3 -m pip install <module_name>
    (Replace <module_name> with your package, e.g. requests, pandas, or numpy).
  2. 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.

  1. Navigate to your project root directory.
  2. Activate the virtual environment:
    source venv/bin/activate       # Or source .venv/bin/activate
  3. Verify that your terminal prompt shows the virtual environment prefix: (venv) user@host:~$.
  4. 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.

  1. Run an inline Python command to print sys.path:
    python3 -c "import sys; print('\n'.join(sys.path))"
  2. Confirm whether the directory containing your package is listed.
  3. 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.

  1. Ensure an __init__.py file exists inside each sub-folder you wish to import as a package:
    touch my_package/__init__.py
  2. 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.

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.