How to Fix Python ModuleNotFoundError and ImportError (2026)

Python dependency errors stop you dead. The error message tells you exactly what is missing, but installing the package and still getting the same error is one of the most common Python frustrations — and it almost always comes down to installing into the wrong environment. This guide covers how to fix ModuleNotFoundError and ImportError correctly, why the environment mismatch happens, and the specific cases where a simple pip install is not enough. Tested on Python 3.10, 3.11, and 3.12 on Ubuntu 22.04 and Windows 11 with WSL2. Last updated March 2026.

If you are running Python inside WSL2 and hitting dependency issues, check the WSL2 installation guide first — a misconfigured WSL2 environment is sometimes the actual cause. For managing Python packages at scale see the Python dependency management guide.

ModuleNotFoundError vs ImportError — What Each One Actually Means

These two errors are not the same thing and fixing them sometimes requires different approaches.

ModuleNotFoundError means Python could not find the module at all — it is not installed in the environment currently running your script, or it is installed somewhere Python is not looking.

ModuleNotFoundError: No module named 'requests'

ImportError means Python found the module but failed while loading it. This happens when a package is installed but one of its own dependencies is missing, when there is a version mismatch, or when a compiled extension (.so or .pyd file) cannot load because a system library is absent.

ImportError: cannot import name 'DataFrame' from 'pandas'

ImportError: libgomp.so.1: cannot open shared object file: No such file or directory

The second ImportError example is from a missing system library — pip install alone will not fix it. That case is covered separately below.

Step 1 — Check Which Python Environment Is Actually Running

Before installing anything, find out which Python interpreter is executing your script. This is the step most people skip, and it is why they end up installing the package three times and still seeing the same error.

# Linux / macOS / WSL2
which python3
which pip3

# Windows PowerShell
where python
where pip

Expected output when a virtual environment is active:

/home/username/myproject/venv/bin/python3
/home/username/myproject/venv/bin/pip3

Expected output when no virtual environment is active:

/usr/bin/python3
/usr/bin/pip3

If which python3 and which pip3 point to different locations, anything you install with pip will go to a different environment than the one running your script. That is the mismatch. The safest way to install is always through the interpreter itself:

# This guarantees pip installs into the same Python that runs your script
python3 -m pip install requests

Use python3 -m pip instead of bare pip or pip3 as a habit. It eliminates the mismatch entirely.

Step 2 — Install the Missing Package

python3 -m pip install requests

Expected output:

Collecting requests
  Downloading requests-2.31.0-py3-none-any.whl (62 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 62.6/62.6 kB 1.2 MB/s eta 0:00:00
Installing collected packages: requests
Successfully installed requests-2.31.0

Verify the install worked before running your script:

python3 -c "import requests; print(requests.__version__)"

2.31.0

If that verification command still throws ModuleNotFoundError after a successful install, the interpreter running the verification is different from the one pip installed into. Go back to Step 1.

Packages where the install name differs from the import name

This catches people constantly. The error says No module named 'cv2' but searching PyPI for cv2 finds nothing — because the package is installed under a different name:

• import cv2 → pip install opencv-python
• import PIL → pip install Pillow
• import sklearn → pip install scikit-learn
• import yaml → pip install PyYAML
• import bs4 → pip install beautifulsoup4
• import dateutil → pip install python-dateutil

When the error message module name does not match anything on PyPI, search PyPI for the likely package name rather than the import name. The PyPI page for the correct package will show the import name in the documentation.

Step 3 — If the Package Is Installed But Still Not Found

You have run pip install, it says successfully installed, but the import still fails. Check where pip actually installed it:

python3 -m pip show requests

Name: requests
Version: 2.31.0
Location: /home/username/myproject/venv/lib/python3.11/site-packages

Now check what paths Python is actually searching:

python3 -c "import sys; print('\n'.join(sys.path))"

/usr/lib/python310.zip
/usr/lib/python3.10
/usr/lib/python3.10/lib-dynload
/usr/local/lib/python3.10/dist-packages
/usr/lib/python3/dist-packages

If the Location from pip show does not appear in the sys.path output, Python will never find the package regardless of how many times you install it. This means you are running a different Python version than the one pip installed into. The fix is to either activate the correct virtual environment, or use the fully qualified python path:

# Find all python3 interpreters on the system
which -a python3

# Run your script with the specific interpreter that has the package
/home/username/myproject/venv/bin/python3 your_script.py

ImportError From Missing System Libraries

Some Python packages are wrappers around C libraries. When the C library is not installed on the system, the Python package installs fine but fails to import with an error like:

ImportError: libgomp.so.1: cannot open shared object file: No such file or directory

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

pip install does not fix this — the missing library is a system package, not a Python package. Install it with apt:

# libgomp (needed by numpy, scikit-learn, lightgbm)
sudo apt install libgomp1

# libGL (needed by opencv-python)
sudo apt install libgl1

# libXext (needed by some GUI-related packages)
sudo apt install libxext6

# General build tools needed for packages that compile from source
sudo apt install build-essential python3-dev

After installing the system library, the Python import should work without reinstalling the Python package.

Finding which system library you need: copy the missing .so filename from the error and search for it:

# Find which apt package provides a specific .so file
apt-file search libgomp.so.1

# If apt-file is not installed
sudo apt install apt-file
sudo apt-file update
apt-file search libgomp.so.1

Virtual Environments — Why Every Project Needs One

Installing packages globally (without a virtual environment) eventually breaks things. Two projects requiring different versions of the same library cannot coexist in the same global environment. The first time you install conflicting packages, one of your projects stops working and debugging it is genuinely painful.

# Create a virtual environment for a project
cd ~/myproject
python3 -m venv venv

# Activate it
source venv/bin/activate   # Linux / macOS / WSL2

# Windows PowerShell
.\venv\Scripts\Activate.ps1

After activation your prompt changes to show the environment name:

(venv) username@machine:~/myproject$

Now every pip install goes into this project’s environment only and does not affect anything else on the system. When you are done working on this project:

deactivate

The one thing that catches beginners: if you open a new terminal window, the virtual environment is not active — you have to run source venv/bin/activate again. Nothing is broken, you just need to activate it. If you forget and run pip install in the new terminal, the package goes to the global environment instead of your project environment.

requirements.txt — reproduce your environment anywhere

# Save current environment to requirements.txt
python3 -m pip freeze > requirements.txt

# Install from requirements.txt in a new environment
python3 -m pip install -r requirements.txt

Check the output of pip freeze before saving — it includes every package including transitive dependencies, which can be 50+ lines even for a simple project. If you only want your direct dependencies, list them manually in requirements.txt with loose version pins (requests>=2.28) rather than exact pins from pip freeze (requests==2.31.0). Exact pins from pip freeze are better for production deployments where you want reproducible builds.

Fix a Corrupted or Broken Package Installation

Occasionally a package install is interrupted or a package file gets corrupted. The symptom is an ImportError with a message that looks like an internal Python error rather than a missing dependency:

ImportError: cannot import name '_imaging' from 'PIL'

Force reinstall clears the broken files and downloads fresh:

# Force reinstall
python3 -m pip install --force-reinstall Pillow

# If that still fails, clear pip cache first
python3 -m pip cache purge
python3 -m pip install --force-reinstall Pillow

Expected output from pip cache purge:

Files removed: 23

Fixing Dependency Errors in Jupyter Notebooks

Jupyter notebooks run their own kernel which may be a different Python environment than your terminal. Installing a package in your terminal and then finding it missing in Jupyter is a separate environment mismatch problem.

Check which Python Jupyter is using from inside a notebook cell:

import sys
print(sys.executable)

/home/username/myproject/venv/bin/python3

Install the package into that exact interpreter from inside the notebook:

import subprocess
import sys
subprocess.check_call([sys.executable, "-m", "pip", "install", "requests"])

This guarantees the install goes into the same Python the notebook kernel is using, regardless of which environment your terminal is in. Restart the kernel after installing, then import normally.

Avoid Using sudo With pip

Do not run sudo pip install. It installs packages into the system Python as root, which can break system tools that depend on specific package versions. On Ubuntu 22.04 and newer, pip will refuse to install into the system Python by default and tell you to use a virtual environment instead:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, use apt.

hint: See PEP 668 for the full story.

This is intentional. The correct response is to use a virtual environment. If you genuinely need a package available system-wide without a venv, use apt where available:

# Install numpy system-wide correctly
sudo apt install python3-numpy

# Check what Python packages are available via apt
apt search python3-

For more on structuring Python dependency management across projects see the Python dependency management guide. For running Python on a Linux environment under Windows see the WSL file transfer guide — moving project files correctly between Windows and WSL2 prevents a separate class of environment issues.