Why Python Fails with ModuleNotFoundError and How to Fix It

The ModuleNotFoundError error in Python means that the interpreter could not find a module while executing an import. To fix it, determine which Python is being used, check the environment, and make sure the dependency is installed in the same environment from which the program is run.

What ModuleNotFoundError Means

The ModuleNotFoundError exception appears when Python tries to load a module:

import requests

If the module is not available in Python's search paths, execution stops with an error:

ModuleNotFoundError: No module named 'requests'

Common causes of the problem:

• the package is not installed in the current environment;
• a different Python interpreter is being used than the one where the package was installed;
• the virtual environment is not activated or the wrong environment is selected;
• the package name used for installation differs from the name used in import;
• a local file or directory affects module lookup.

Before installing a dependency, check which Python interpreter actually runs the code. In many cases the package is installed, but not in the environment used by the application or IDE.

Applicable Python Versions and Limitations

The methods in this article apply to modern Python 3 versions, including environments using the venv module and package installation through pip. Specific commands may differ depending on the operating system, Python installation method, and selected environment manager.

If a project uses conda, Poetry, Pipenv, or another dependency management tool, use that tool's commands. Examples with python -m pip apply to environments where dependencies are managed through pip.

Quick Diagnostic Scenario

The cause of the error usually depends on when it appeared:

• After installing a package: verify that installation was performed for the same interpreter that runs the program.
• After changing IDE: compare the selected interpreter in the editor with the result of sys.executable in the terminal.
• After cloning a project: create or activate an environment and install dependencies from the project file.

Checking the Python Interpreter in Use

First determine the interpreter that runs the program:

python --version
python -c "import sys; print(sys.executable)"

On some systems, python3 is used instead of python:

python3 --version
python3 -c "import sys; print(sys.executable)"

The sys.executable value shows the path to the interpreter that is actually being used. Compare it with the project and IDE settings.

Checking the Interpreter in an IDE

If the error occurs only when running from a code editor, check the selected project environment. An IDE may use a different Python than the terminal.

• open the project interpreter settings;
• select the environment that matches the required Python installation;
• compare the path with the result of sys.executable;
• run the program again after changing the settings.

Checking Package Installation

Check that the dependency exists using the same Python that runs the program:

python -m pip show package_name

For example:

python -m pip show requests

To view installed packages, use:

python -m pip list

The python -m pip form connects the pip call with a specific interpreter and helps avoid installing a package into another environment.

Fixing the Issue by Installing the Dependency

If the package is missing, install it into the selected environment:

python -m pip install package_name

After installation, verify the import:

python -c "import module_name; print('ok')"

The package name and module name may differ. For example, the name used in the installation command does not always match the name used after import, so check the documentation for the specific library.

Checking the Virtual Environment

Virtual environments isolate project dependencies. A package installed globally is not necessarily available inside the application's environment.

Create an environment using Python's standard module:

python -m venv .venv

Activation depends on the operating system.

Windows:

.venv\Scripts\activate

Linux and macOS:

source .venv/bin/activate

After activation, check the environment again:

python -c "import sys; print(sys.executable)"
python -m pip list

If conda Is Used

In conda projects, first check the active environment and use the package manager that manages it:

conda env list
conda list

If a package should be installed through conda, use the appropriate installation command. If some dependencies are installed through pip inside a conda environment, make sure that pip belongs to the same Python interpreter.

python -m pip show package_name

Checking the Dependency File

If the project contains a dependency list, install it completely. This is usually more reliable than fixing each import error separately.

For a requirements.txt file, use:

python -m pip install -r requirements.txt

After successfully configuring the environment, current dependencies can be saved:

python -m pip freeze > requirements.txt

For projects using other managers, use the project's standard dependency locking mechanism, such as Poetry or Pipenv configuration files.

Searching for Name Conflicts

Sometimes the issue is not a missing package but which module is loaded. For example, a project may contain a file with the same name as an installed library:

project/
├── requests.py
└── main.py

Python searches for modules using paths from sys.path. In a typical execution structure, the project directory may be included in these paths, so a local file can affect the import result before the installed package. The exact order depends on the launch method and environment settings.

The location of a loaded module can only be checked after a successful import:

python -c "import module_name; print(module_name.__file__)"

If the import fails with ModuleNotFoundError, first check the interpreter, environment, and installed packages.

Diagnosing Through sys.path

Python uses the sys.path list to search for modules. The actual value can be viewed with:

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

The contents of sys.path depend on the launch method, virtual environment, Python installation type, and project settings. A missing expected path may indicate an incorrect environment, but manually changing sys.path usually does not replace correct dependency installation.

Common Errors and Solutions

Verifying the Result

After fixing the issue, perform a sequential check:

1. Check the running Python path using sys.executable.
2. Make sure the package is installed in this exact environment.
3. Check IDE settings if the program is launched through an editor.
4. Check the module location using module.__file__ only after a successful import.
5. Run the application or tests again.
6. Save working dependencies, for example by creating an updated requirements.txt with python -m pip freeze > requirements.txt or using the selected project's dependency manager.

Final Checklist

• The Python interpreter executing the code has been identified.
• The active project environment has been checked.
• The package has been verified through the same Python interpreter and dependency manager.
• IDE settings match the project environment.
• File and directory name conflicts have been excluded.
• Dependencies are saved using the project's accepted method.

Verification Limitations

Commands and environment locations may differ depending on the operating system, Python version, and selected dependency management tool. For conda, Poetry, Pipenv, and other managers, use the documentation for the specific tool.

Sources

• Python Documentation: Built-in Exceptions
• Python Documentation: venv — Creation of virtual environments
• pip Documentation
• Python Packaging User Guide