How to Fix ‘ModuleNotFoundError: No Module Named’ in Python on Ubuntu

Executing a Python script, launching a web service, or deploying a machine learning workflow on Ubuntu only to be halted by the runtime exception “ModuleNotFoundError: No module named ‘example_module'” indicates that the Python interpreter cannot resolve the requested library import statement within its sys.path search hierarchy. In modern Ubuntu releases (including Ubuntu 22.04 LTS and 24.04 LTS), system Python environments are strictly managed under PEP 668 (“externally-managed-environment”), preventing arbitrary global pip install executions. When libraries are installed under a different Python version, packages exist in an unactivated virtual environment, or custom project modules are missing from the system path, execution crashes immediately. This guide explains how to properly install prerequisite modules, manage virtual environments, and resolve Python module discovery failures on Ubuntu.

What Causes ModuleNotFoundError in Python on Ubuntu?

Python imports modules by traversing directories defined within its internal sys.path array:

  • Uninstalled Python Library: The script imports a package (such as requests, numpy, or pandas) that has not been installed into the active Python environment.
  • Multiple Python Versions Installed: The module was installed via pip3.10, but the script is executed using python3.12.
  • Unactivated Python Virtual Environment: Packages reside within an isolated .venv or conda directory, but the terminal session is running against system Python binaries.
  • PEP 668 Externally Managed Environment: Ubuntu blocking global pip commands, resulting in aborted or partial package installations.
  • Missing PYTHONPATH Directory Declaration: Custom project subfolders and package hierarchies omitted from the operating system environment search paths.

Method 1: Verify Python Version and Install via APT or Pip

Ensure that packages are installed into the exact Python version executing your script.

  1. Check which Python binary is currently active:
    python3 --version
    which python3
  2. Many fundamental Python libraries are available directly through native Ubuntu repositories. For example, install common libraries via apt:
    sudo apt update
    sudo apt install python3-requests python3-numpy python3-pip
  3. If the library is not packaged by Canonical, avoid breaking system Python by installing it into your user space:
    python3 -m pip install --user example_module

Method 2: Create and Activate a Dedicated Virtual Environment

Using isolated virtual environments is the recommended standard on modern Ubuntu systems to prevent library conflicts.

  1. Install the Python virtual environment package if not already present:
    sudo apt install python3-venv python3-full -y
  2. Navigate to your project root folder:
    cd ~/my_project
  3. Create a fresh virtual environment:
    python3 -m venv venv
  4. Activate the virtual environment:
    source venv/bin/activate
  5. Your terminal prompt will now display (venv). Install required packages directly:
    pip install example_module
  6. Run your script within the activated environment:
    python script.py

Method 3: Configure the PYTHONPATH Environment Variable

If your script fails to import custom modules located in adjacent project directories, explicitly declare the module root path.

  1. Temporarily execute the script by defining PYTHONPATH:
    PYTHONPATH=. python3 script.py
    (The period tells Python to include the current working directory in module searches.)
  2. To include an absolute directory path permanently, export it in your terminal session:
    export PYTHONPATH="/home/user/my_project/src:$PYTHONPATH"
  3. Verify that the directory is visible to Python:
    python3 -c "import sys; print(sys.path)"

Method 4: Fix Import Name vs Package Name Discrepancies

Certain Python packages use a PyPI installation name that differs fundamentally from the module import statement.

  1. Examine common discrepancies:
    • To import PIL, install: pip install Pillow
    • To import cv2, install: pip install opencv-python
    • To import yaml, install: pip install PyYAML
    • To import bs4, install: pip install beautifulsoup4
    • To import sklearn, install: pip install scikit-learn
  2. If your script imports cv2 but fails, execute:
    pip install opencv-python
  3. Re-run your script to confirm module import success.

Get the best tech tips delivered straight to your inbox.

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