How to Fix ImportError in Python: 5 Common Causes and Solutions

Few things frustrate a Python beginner more than seeing “ImportError: No module named…” when you are trying to get something working. The good news is that import errors almost always come from one of five causes, and each one has a straightforward fix.

In this guide, you will learn what causes ImportError and ModuleNotFoundError, how to diagnose the problem, and how to fix it every time.

What Is an ImportError?

When you write import something in Python, the interpreter searches for that module in specific locations. If it cannot find the module, you get an error.

There are two related errors:

• ImportError — the module exists but something inside it cannot be imported
• ModuleNotFoundError — Python cannot find the module at all (this is a subclass of ImportError)

# This will fail if 'pandas' is not installed
import pandas as pd

Error message:

ModuleNotFoundError: No module named 'pandas'

Cause 1: The Module Is Not Installed

This is the most common cause. You are trying to import a third-party package that has not been installed in your current Python environment.

How to Fix It

Install the package using pip:

# Run in your terminal (not inside Python)
# pip install pandas

Verify the installation:

import pandas as pd
print(f"pandas version: {pd.__version__}")

Output:

pandas version: 2.2.0

Common Mistake: Wrong pip Version

If you have both Python 2 and Python 3 installed, pip might point to the wrong version.

# Use pip3 explicitly or python -m pip
# python3 -m pip install pandas
# python -m pip install pandas

You can check which Python your pip is linked to:

import sys
print(sys.executable)

Output:

/usr/local/bin/python3.12

Cause 2: Virtual Environment Not Activated

You installed the package globally, but your project uses a virtual environment (or vice versa). The package exists somewhere, just not where your current Python is looking.

How to Fix It

Activate your virtual environment first, then install:

# Terminal commands:
# source venv/bin/activate        (Linux/Mac)
# venv\Scripts\activate           (Windows)
# pip install pandas

Check if you are in a virtual environment:

import sys
print(sys.prefix)
print(sys.base_prefix)
# If these are different, you are in a virtual environment

Output:

/home/user/project/venv
/usr/local

Cause 3: File Name Conflicts

If you name your own Python file the same as a module you are trying to import, Python imports your file instead of the actual library.

Example of the Problem

You create a file called random.py:

# File: random.py (BAD name - conflicts with stdlib)
import random  # This imports YOUR file, not Python's random module

number = random.randint(1, 10)
print(number)

Error:

AttributeError: module 'random' has no attribute 'randint'

How to Fix It

Rename your file to something that does not conflict with any Python module:

# File: my_random_game.py (GOOD name)
import random

number = random.randint(1, 10)
print(f"Random number: {number}")

Output:

Random number: 7

Also delete any __pycache__ folder and .pyc files left over from the conflicting file:

# Terminal:
# rm random.py
# rm -rf __pycache__

Cause 4: Incorrect Import Path

Your module exists but Python cannot find it because it is in a different directory or the path is wrong.

How to Fix It

Check where Python is looking for modules:

import sys
for path in sys.path:
    print(path)

Output:

/home/user/project
/usr/lib/python3.12
/usr/lib/python3.12/lib-dynload
/usr/local/lib/python3.12/dist-packages

If your module is in a subdirectory, you need to use the correct import syntax:

# Project structure:
# project/
#   main.py
#   utils/
#     __init__.py
#     helpers.py

# In main.py:
from utils.helpers import my_function
print(my_function())

Make sure each package directory has an __init__.py file (can be empty):

# Create __init__.py in the utils folder
# This tells Python the folder is a package

# utils/__init__.py
# (this file can be empty)

Cause 5: Circular Imports

Two modules try to import each other, creating an infinite loop that Python breaks by raising an ImportError.

Example of the Problem

# file_a.py
from file_b import function_b

def function_a():
    return "A"

# file_b.py
from file_a import function_a  # Circular!

def function_b():
    return "B"

Error:

ImportError: cannot import name 'function_a' from partially initialized module 'file_a'

How to Fix It

Move the import inside the function that needs it:

# file_a.py
def function_a():
    return "A"

def call_b():
    from file_b import function_b  # Import inside function
    return function_b()

print(call_b())

Output:

B

Or restructure your code so shared utilities go into a third file that both modules can import without circularity.

Quick Diagnostic Script

Run this script to diagnose any import error:

import sys
import importlib

module_name = "pandas"  # Change this to your module

# Check Python version
print(f"Python: {sys.version}")
print(f"Executable: {sys.executable}")

# Try importing
try:
    mod = importlib.import_module(module_name)
    print(f"Successfully imported '{module_name}'")
    print(f"Location: {mod.__file__}")
except ModuleNotFoundError:
    print(f"Module '{module_name}' is NOT installed")
    print(f"Fix: pip install {module_name}")
except ImportError as e:
    print(f"ImportError: {e}")

Output (when module is installed):

Python: 3.12.4 (main, Jun 10 2026, 00:00:00)
Executable: /usr/local/bin/python3.12
Successfully imported 'pandas'
Location: /usr/local/lib/python3.12/dist-packages/pandas/__init__.py

Summary Table

FAQ

What is the difference between ImportError and ModuleNotFoundError?

ModuleNotFoundError is a more specific type of ImportError introduced in Python 3.6. It appears when Python cannot find the module at all. ImportError is broader and can also appear when the module is found but a specific name inside it cannot be imported.

Why does pip install work but the import still fails?

This usually means pip installed the package for a different Python version than the one you are running. Use python -m pip install package_name to ensure you install for the correct Python interpreter.

How do I fix ImportError in VS Code?

Make sure VS Code is using the correct Python interpreter. Press Ctrl+Shift+P, type “Python: Select Interpreter,” and choose the one that has your packages installed (usually your virtual environment).

Can I have import errors with built-in modules?

Rarely, but yes — usually caused by naming your own file the same as a built-in module (like naming your file os.py or sys.py). Always avoid using standard library names for your files.

How do I see all installed packages?

Run pip list or pip freeze in your terminal. Inside Python, you can use import pkg_resources; print([p.project_name for p in pkg_resources.working_set]) to list all available packages.