ModuleNotFoundError

ModuleNotFoundError: No module named 'foo'

Traceback

terminal

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import numpy as np  # not installed
ModuleNotFoundError: No module named 'foo'

What causes this error

The specified module is not installed, the module name is misspelled, the wrong virtual environment is active, or a local file shadows the module name.

How to fix it

Install the package: `pip install module_name`. Activate the correct virtual environment. Check if the pip package name differs from the import name. Ensure no local file shadows the module.

Code that causes this error

Broken

import numpy as np  # not installed

Fixed code

Fixed

# First: pip install numpy
import numpy as np

About ModuleNotFoundError

This is the standard ModuleNotFoundError message indicating that Python could not locate the specified module. The troubleshooting steps follow a consistent checklist: verify the module name is spelled correctly, check if the package is installed (`pip list | grep module`), ensure you are using the correct Python environment or virtual environment, check if a local file shadows the module name, and verify `sys.path` includes the directory containing the module. A particularly tricky case is when the pip install name differs from the import name — for example, `pip install Pillow` but `import PIL`, or `pip install python-dateutil` but `import dateutil`.

The `pip show` command reveals where a package is installed, which helps verify it is in the right environment.

Common scenarios

Installing packages in a different virtual environment than the one in use

Circular imports between modules that depend on each other

Typos in module or package names in import statements

Naming a local file the same as a standard library module