21 min read

What Causes ModuleNotFoundError in Python?

Python is one of the most popular programming languages for web development, data science, artificial intelligence, automation, and software engineering. Its extensive ecosystem of libraries and packages allows developers to build applications without writing every feature from scratch. However, when importing a library or module, you may encounter the Python ModuleNotFoundError exception.

This error commonly appears as ModuleNotFoundError: No module named 'requests' or ModuleNotFoundError: No module named 'numpy'. It means Python cannot locate the module you are trying to import using its current module search paths. The package might not be installed, the wrong Python interpreter might be running, or your project configuration might be incorrect.

Understanding the common causes of Python module import errors helps you troubleshoot problems efficiently instead of repeatedly installing packages without identifying the underlying issue.

In this guide, you will learn what causes ModuleNotFoundError in Python, how to fix ModuleNotFoundError: No module named, how Python searches for modules, and how to prevent similar problems using virtual environments, dependency management tools, and practical debugging techniques.

What Is ModuleNotFoundError in Python?

ModuleNotFoundError is a built-in Python exception raised when the import system cannot find a module that your code attempts to import.

Consider this example:

import requests

response = requests.get("https://example.com")
print(response.status_code)

If the requests package is unavailable to the active Python environment, Python may display this error:

ModuleNotFoundError: No module named 'requests'

The code itself might be valid. The problem is that Python cannot find the required module.

Python uses an import system to locate modules in several places, including the current project directory, standard library locations, and installed package directories such as site-packages.

When the requested module cannot be found, Python raises an exception to indicate that the import failed.

Why Does Python Raise This Error?

The most common causes include:

• The required Python package is not installed.
• The package was installed in a different Python environment.
• Your IDE is using the wrong Python interpreter.
• The module name differs from the package installation name.
• A virtual environment is not activated correctly.
• Python’s module search path does not include the required directory.
• The package is incompatible with your Python version.
• Your project contains a local module naming conflict.
• A dependency installation failed or was incomplete.
• The package is available in one environment but missing from another, such as a Docker container.

Identifying the correct cause is essential because each situation requires a different solution.

What Causes ModuleNotFoundError in Python?

Several configuration and dependency issues can trigger this exception. Understanding them makes debugging faster and helps you avoid unnecessary package installations.

1. The Required Python Package Is Not Installed

The most common cause is attempting to import a third-party package that has not been installed.

For example:

import flask

If Flask is missing from the active environment, Python cannot import it.

You can install the package using:

python -m pip install flask

Alternatively, you can use:

pip install flask

On systems where pip3 is configured for the intended Python installation, the following command may also work:

pip3 install flask

Using python -m pip install is often preferable because it associates the package installation command with a specific Python interpreter.

After installation, test the import:

import flask

print(flask.__version__)

The exact version-reporting interface can vary by package, so checking the installed package with pip show is another reliable option.

2. Python Interpreter Mismatch

A Python interpreter mismatch occurs when you install a package using one Python installation but execute your application with another.

For example, your computer might contain:

• Python 3.10
• Python 3.12
• A project-specific virtual environment
• A Conda environment

Suppose you run:

pip install requests

The command installs requests into one environment, but your application runs under another interpreter. Python may still report that the module is missing.

Check the Python version:

python --version

Check the interpreter location:

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

Then install the package using that interpreter:

python -m pip install requests

If your system uses the python3 command, run:

python3 -m pip install requests

The goal is to make sure the Python interpreter running your application can access the package you installed.

3. Virtual Environments Are Not Configured Correctly

Virtual environments isolate project dependencies so different applications can use different package versions.

Python supports virtual environments through venv, while the third-party virtualenv package offers another option.

For example, one project might require Django 4, while another project requires a different Django version. Separate environments help prevent dependency conflicts.

Create a virtual environment:

python -m venv .venv

Activate it on Windows:

.venv\Scripts\activate

Activate it on macOS or Linux:

source .venv/bin/activate

Install the required package:

python -m pip install requests

Verify that the environment is active:

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

If the displayed path points to the expected .venv directory, your application is using the intended interpreter.

Remember that activating a virtual environment in one terminal does not automatically activate it in every terminal, IDE, notebook, or background process.

4. Incorrect Package Names Versus Import Names

Some Python packages have installation names that differ from their import names.

This distinction frequently confuses beginners.

For example:

If you try to install a package using its import name, the installation may fail or install a different distribution.

For Beautiful Soup, use:

python -m pip install beautifulsoup4

Then import it using:

from bs4 import BeautifulSoup

For OpenCV, use:

python -m pip install opencv-python

Then import it using:

import cv2

Always distinguish between the distribution name used by the package manager and the module name used in Python code.

5. Python Module Search Paths Are Incorrect

Python uses sys.path to determine where it should search for importable modules.

You can inspect the search paths with:

import sys

for path in sys.path:
    print(path)

The output typically includes locations associated with the project, the standard library, and installed packages.

If a module exists in a directory that is not included in the import search path, Python may not find it.

The PYTHONPATH environment variable can add directories to Python’s module search path.

For example, on Linux or macOS:

export PYTHONPATH="/path/to/my/project"

On Windows Command Prompt:

set PYTHONPATH=C:\path\to\my\project

Use PYTHONPATH carefully because changing import paths globally can introduce confusing behavior. For most applications, a properly structured project or an editable installation is a better solution.

6. Missing __init__.py or Incorrect Project Structure

Python projects often use packages to organize code into directories.

Consider this structure:

my_project/
    main.py
    utilities/
        __init__.py
        helpers.py

Your application can import a function from the helpers module:

from utilities.helpers import some_function

In traditional package layouts, __init__.py marks a directory as a regular Python package. Modern Python also supports implicit namespace packages, so this file is not required in every package directory.

If imports fail, verify that your files are arranged correctly and that the code is running from the intended project context.

A missing __init__.py is not automatically the cause of every ModuleNotFoundError. Incorrect working directories, package layouts, and import statements can produce similar symptoms.

7. Local Module Naming Conflicts

A local file can accidentally interfere with an import.

For example, creating a file named requests.py in your project can shadow the third-party requests package.

Similarly, names such as json.py, random.py, or typing.py can conflict with standard library modules.

Rename the conflicting file and remove any associated __pycache__ files if stale bytecode is involved. Then restart the Python process and try the import again.

To inspect which module Python actually loads, run:

import requests

print(requests.__file__)

If the path points to your project directory instead of the expected installed package, investigate the naming conflict.

8. Python Version Compatibility

Some packages support only specific Python versions or operating systems.

For example, a package might require a newer Python version than the one installed on your machine.

Check your version:

python --version

Inspect the installed package:

python -m pip show requests

For packages that have version restrictions, consult their documentation and installation metadata.

Python version compatibility problems may cause installation errors, missing compatible wheels, or import failures involving unavailable modules and dependencies.

How to Fix ModuleNotFoundError: No module named

The most effective approach is to follow a consistent troubleshooting process rather than randomly reinstalling Python or deleting project files.

Step 1: Identify the Missing Module

Read the complete traceback and locate the missing module name.

For example:

ModuleNotFoundError: No module named 'numpy'

The missing module is numpy.

If the error occurs inside a dependency, the missing module might not be the package directly imported by your code. Read the traceback carefully to identify which component is requesting it.

Step 2: Check Whether the Package Is Installed

Run:

python -m pip show numpy

If the package is installed in the selected environment, the command displays information such as its version and installation location.

You can also list installed packages:

python -m pip list

If the package is absent, install it:

python -m pip install numpy

Step 3: Verify the Python Interpreter

Run:

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

Compare the displayed path with the interpreter selected by your development environment.

If they differ, configure the application to use the intended interpreter.

Step 4: Test the Import Directly

Run:

python -c "import numpy; print(numpy.__version__)"

If this succeeds, the package is available to that interpreter.

If it fails, continue checking the environment, package installation, and import configuration.

Step 5: Check Package Dependencies

Some packages rely on other packages to work correctly.

For example, a web application may depend on Flask, database drivers, and environment-variable utilities.

Inspect installed package details:

python -m pip show flask

Export the environment’s installed package versions:

python -m pip freeze

Compare the output with your project’s requirements.txt file.

Install project dependencies using:

python -m pip install -r requirements.txt

If the problem is caused by an incompatible dependency version, review the package constraints rather than upgrading everything indiscriminately.

Step 6: Restart the Development Environment

After installing a package, restart the Python process if necessary.

In Jupyter Notebook, restart the kernel. In an IDE, confirm the selected interpreter and restart the relevant run session. For long-running web servers, restart the application process.

This ensures that the running process uses the updated environment.

Common ModuleNotFoundError Examples and Their Solutions

Different libraries can produce the same exception. The correct solution depends on the package involved and the environment where the error occurs.

ModuleNotFoundError: No module named 'requests'

Install Requests:

python -m pip install requests

Test the installation:

import requests

response = requests.get("https://example.com", timeout=10)
print(response.status_code)

If the error persists, verify the active interpreter and confirm that the package was installed into the correct environment.

ModuleNotFoundError: No module named 'numpy'

NumPy is widely used for numerical computing and array operations.

Install it with:

python -m pip install numpy

Then test:

import numpy as np

values = np.array([10, 20, 30])
print(values.mean())

Missing pandas or matplotlib

For data analysis and visualization, install the required libraries:

python -m pip install pandas matplotlib

Import them using:

import pandas as pd
import matplotlib.pyplot as plt

If either import fails, verify that both packages were installed in the same environment used to run the script.

Missing Flask or Django

Flask and Django are popular Python web frameworks.

Install Flask:

python -m pip install flask

Install Django:

python -m pip install django

Import Flask:

import flask

Import Django:

import django

When working with web applications, install dependencies in the project’s virtual environment and document them in requirements.txt.

Missing bs4, cv2, sklearn, PIL, or dotenv

These module names correspond to commonly used packages:

python -m pip install beautifulsoup4 opencv-python scikit-learn Pillow python-dotenv

Example imports:

from bs4 import BeautifulSoup
import cv2
import sklearn
from PIL import Image
from dotenv import load_dotenv

Installing all these libraries is unnecessary unless your project actually uses them. Install only the dependencies your application requires.

Missing selenium, torch, or tensorflow

These libraries support browser automation and machine learning.

Install Selenium:

python -m pip install selenium

Install PyTorch using the command recommended by its official installation selector because the appropriate package depends on your operating system and hardware configuration.

Install TensorFlow using the installation instructions for your Python version and platform.

Then test the relevant import:

import selenium
import torch
import tensorflow

Large machine-learning frameworks can have additional compatibility requirements. A failed installation should be investigated before assuming the module is simply missing.

Missing openai, discord, or mysql.connector

Install the appropriate distribution:

python -m pip install openai discord.py mysql-connector-python

Then use the correct import statements:

import openai
import discord
import mysql.connector

The installed distribution name does not always match the module name, so checking official package documentation is important.

How to Fix ModuleNotFoundError in Different Development Environments

ModuleNotFoundError in VS Code

Visual Studio Code can use a different Python interpreter from the one associated with your terminal.

To fix the problem:

1. Open your project in VS Code.
2. Open the Command Palette.
3. Select Python: Select Interpreter.
4. Choose the interpreter or virtual environment used by your project.
5. Open a new terminal.
6. Install the missing package using python -m pip install package_name.
7. Run your Python script again.

For additional debugging, print sys.executable inside your script and compare it with the interpreter you selected.

ModuleNotFoundError in PyCharm

PyCharm associates projects with configured Python interpreters.

Open the project settings and locate the Python interpreter configuration. Select the correct virtual environment or add the intended interpreter.

Then install the missing package through the integrated package manager or the terminal associated with that environment.

Check that the Run Configuration uses the same interpreter as the one where you installed the dependency.

ModuleNotFoundError in Jupyter Notebook

Jupyter Notebook can run a kernel that differs from the Python environment where you installed your packages.

Check the active kernel:

import sys

print(sys.executable)

Install the package using the current kernel’s interpreter:

import sys
import subprocess

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

This method directs pip to the interpreter running the notebook.

Restart the kernel after installation if necessary, then test the import again.

ModuleNotFoundError in Google Colab

Google Colab provides a managed Python environment, and installed packages may not persist across runtime resets.

Install a missing dependency in a notebook cell:

%pip install requests

Then import it:

import requests

If a package becomes unavailable after a runtime reset, install it again in the new session.

ModuleNotFoundError in Anaconda

Anaconda uses Conda environments to manage Python versions and dependencies.

List available environments:

conda env list

Activate the intended environment:

conda activate myenv

Install the required package:

conda install numpy

For packages unavailable through your configured Conda channels, pip may be appropriate:

python -m pip install package_name

Avoid mixing incompatible Conda and pip dependencies without understanding the resulting environment changes.

Fixing ModuleNotFoundError on Windows, macOS, and Linux

Windows

Windows systems can contain several Python installations, including versions installed through the official installer, Microsoft Store, or development tools.

Check available Python installations:

py -0p

Run a specific installed version when appropriate:

py -3.12 -m pip install requests

The version shown is an example; use a version installed on your system.

If pip is not recognized, try:

py -m pip --version

If pip is missing, bootstrap it when supported:

py -m ensurepip --upgrade

macOS

On macOS, use the Python interpreter associated with your project:

python3 --version
python3 -m pip --version
python3 -m pip install requests

If you are using a virtual environment, activate it before installing packages.

Avoid changing the system-managed Python installation unnecessarily.

Linux

On Linux, use the appropriate Python command:

python3 --version
python3 -m pip --version

Install the dependency in a virtual environment whenever possible:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests

Some Linux distributions manage system Python packages through their operating system package manager. If you encounter an externally managed environment error, use a virtual environment instead of forcing a system-wide pip installation.

Python Package Installation Errors and Dependency Conflicts

Sometimes the package is not missing because you forgot to install it. Instead, its installation may have failed or its dependencies may be incompatible.

Common Python package installation errors include:

• Permission denied during installation.
• Unsupported Python version.
• No compatible distribution found.
• Network or package-index connectivity failures.
• Conflicting dependency requirements.
• Incomplete installations.
• Restrictions imposed by an externally managed Python environment.

Check Installation Permissions

If pip reports a permission error, avoid automatically running every command with administrator privileges.

Create and activate a virtual environment, then install the package inside it.

Resolve Dependency Conflicts

Use:

python -m pip check

This command checks installed packages for incompatible or missing declared dependencies.

If you maintain a project with multiple dependencies, update requirements.txt carefully and test the application after changing package versions.

Use pip freeze and requirements.txt

Create a dependency snapshot:

python -m pip freeze > requirements.txt

Install the recorded dependencies in another environment:

python -m pip install -r requirements.txt

A requirements file improves reproducibility, although you should review its contents and avoid treating an uncontrolled snapshot as a carefully maintained dependency specification.

Advanced Causes: Circular Imports, Editable Installs, and Docker

Circular Imports

A circular import occurs when two or more modules depend on each other during initialization.

For example, module A imports module B, while module B imports module A.

Circular imports more commonly cause partially initialized module errors or ImportError, rather than a straightforward ModuleNotFoundError. However, complex import structures can make debugging confusing.

Reduce unnecessary circular dependencies, move shared functionality into a separate module, or reorganize imports to make dependencies clearer.

Editable Installs

Editable installs are useful when developing a local Python package.

For a project with a valid package configuration, run:

python -m pip install -e .

This allows Python to import the package from the development source without requiring a fresh standard installation after every code change.

Editable installs still require the package’s build configuration and environment to be correct.

Docker Python Dependencies

A package installed on your host computer is not automatically available inside a Docker container.

For example, a Docker image might use:

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .

RUN python -m pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "main.py"]

This example assumes that requirements.txt contains the dependencies required by main.py.

If the container reports ModuleNotFoundError, check the image build, dependency file, active container interpreter, and whether the latest image was rebuilt after dependency changes.

Managing Dependencies with Poetry, Pipenv, and uv

Modern Python projects can use dependency management tools to simplify package installation and environment configuration.

Poetry

Poetry manages project dependencies and packaging through pyproject.toml and its lock file.

Typical commands include:

poetry install
poetry run python main.py

These commands install project dependencies and run the application in Poetry’s managed environment.

Pipenv

Pipenv manages dependencies using Pipfile and Pipfile.lock.

Install dependencies:

pipenv install

Run your script:

pipenv run python main.py

uv

The uv tool provides fast Python package and project management.

For a project configured to use uv, common commands include:

uv sync
uv run python main.py

Choose a dependency manager that suits your project rather than combining several tools without a clear reason.

Troubleshooting Checklist for Python ModuleNotFoundError

Use this checklist whenever Python reports that a module cannot be found.

1. Read the complete traceback and identify the missing module.
2. Check whether the required package is installed.
3. Run python -m pip show package_name.
4. Confirm the active interpreter with sys.executable.
5. Activate the correct virtual environment.
6. Install the correct distribution name rather than guessing from the import name.
7. Inspect sys.path and PYTHONPATH if the module is stored locally.
8. Check for conflicting filenames in the project directory.
9. Review Python version compatibility and package dependencies.
10. Verify your IDE or notebook kernel configuration.
11. Check requirements.txt and run python -m pip check.
12. Restart the Python process and test the import again.

If the problem continues, create a minimal reproducible example that contains only the relevant import and environment details.

How to Prevent ModuleNotFoundError in Python

Preventing missing-module errors is easier than repeatedly fixing them after they appear.

Use One Virtual Environment Per Project

Keep each project’s dependencies isolated. This reduces conflicts between applications that require different library versions.

Document Dependencies

Maintain a clear requirements.txt file or use a dependency manager such as Poetry, Pipenv, or uv.

Record important version constraints so team members can reproduce your development environment.

Avoid Ambiguous Module Names

Do not name your project files after popular standard library modules or third-party packages.

Prefer descriptive names such as http_client.py instead of requests.py when your code implements custom HTTP functionality.

Verify Imports During Development

Test important imports after installing dependencies and include application tests in your development workflow.

Continuous integration pipelines can catch missing dependencies before deployment.

Keep Python Environments Consistent

Use the same documented Python version and dependency configuration across development, testing, and production.

For Docker-based applications, ensure that the container image installs all required dependencies.

If your code encounters other syntax-related problems, you can also read our guide on Python IndentationError to understand why incorrect indentation causes Python code to fail.

Frequently Asked Questions

Conclusion

Python ModuleNotFoundError is usually caused by a missing package, an incorrect interpreter, a virtual environment configuration problem, an invalid import name, or an unexpected module search path.

The best troubleshooting approach is to identify the missing module, verify the active Python interpreter, check the installed packages, and install dependencies into the correct environment. Tools such as python -m pip install, pip show, pip list, pip freeze, sys.path, and sys.executable make it easier to identify the actual problem.

For larger projects, virtual environments, requirements.txt, Conda, Poetry, Pipenv, and uv can help maintain consistent dependencies. Following these practices will make your Python applications easier to debug, reproduce, deploy, and maintain.