ImportError in Python: Causes and Fixes

ImportError means Python could not complete an import statement.

This usually happens because:

the module is missing
the name you are trying to import does not exist
Python is using the wrong environment
your project files are named or arranged in a way that breaks imports

Beginners often mix up ImportError and ModuleNotFoundError.

ModuleNotFoundError is more specific
ImportError is broader
Python may find the module, but still fail to import something from it

This page helps you check the most common causes step by step.

Quick fix checklist

First confirm Python is running correctly, then check whether the module exists, the name is spelled correctly, and the import path is valid.

import sys
print(sys.version)
print(sys.path)

# Check the exact import you are using
import math
print(math.sqrt(9))

What this does:

sys.version shows which Python version is running
sys.path shows where Python looks for modules
import math checks that a standard library import works
math.sqrt(9) confirms the imported module is usable

If a simple import works but your real import fails, the problem is likely with:

the module name
the imported name
the environment
your file or package structure

What ImportError means

ImportError happens when Python cannot complete an import statement.

In simple terms:

Python may fail to find a module
or Python may find the module but fail to load part of it
or Python may find the module but not the specific name you asked for

For example:

import some_module can fail if the module is not available
from some_module import thing can fail if thing does not exist

If you want a broader explanation of imports, see how import works in Python.

When this error happens

You may see ImportError in situations like these:

importing a module that is missing
importing a name that does not exist inside a module
using the wrong Python environment
running a file from the wrong folder
circular imports between your own files
naming your file the same as a standard library module

These are the most common beginner cases.

Basic example that causes ImportError

A common case is importing a name that is not available inside a module.

from math import square_root

This fails because the math module exists, but square_root is not a valid name in that module.

The correct name is sqrt.

from math import sqrt

print(sqrt(9))

Output:

3.0

This is an important pattern:

Python can find the module
but Python cannot import the requested name

That is different from a missing module.

For a more specific version of this problem, see ImportError: cannot import name.

Fix 1: Check the module and name carefully

Start with the simplest possibility: a typo.

Check these things:

spelling
uppercase and lowercase letters
whether the function, class, or variable really exists
whether you are using the correct module

For example, this is wrong:

from math import Sqrt

This is correct:

from math import sqrt

Python names are case-sensitive. Sqrt and sqrt are different names.

If you are not sure what a module contains, import the whole module first:

import math

print(dir(math))

dir() shows the available names inside the module.

You can also inspect help text with Python’s built-in tools. See Python dir() explained and Python help() explained.

A safe pattern is:

import math

print(math.sqrt(16))

This helps you confirm:

the module imports correctly
the member name is valid

Fix 2: Check your environment and installed packages

Sometimes the package is installed, but not in the Python environment you are actually using.

This often happens when:

your editor uses a different interpreter
your terminal uses a different Python installation
you forgot to activate a virtual environment

Useful checks:

python --version
python -m pip --version
python -m pip list

A good habit is to install packages like this:

python -m pip install package_name

This makes pip run with the same Python interpreter as python.

If you are using a virtual environment, activate it before running your script.

If imports work in one editor but not another, they may be using different interpreters.

If you need help with setup, see how to create and use a virtual environment in Python.

Fix 3: Check your file and folder names

A local file can shadow a real module.

For example, if your file is named random.py, this can break code like:

import random

Python may import your local file instead of the standard library module.

Problem filenames include:

random.py
json.py
os.py
sys.py

Rename the file to something else, such as:

my_random_script.py
json_example.py

After renaming, you may also need to remove cached files:

__pycache__/
old .pyc files

This is a very common beginner mistake.

Fix 4: Check package structure and relative imports

Imports can fail if your files are run from the wrong location.

Imagine a project like this:

project/
    app/
        __init__.py
        main.py
        utils.py

If main.py contains:

from app import utils

running the file from the correct place matters.

Often this works better from the project root:

python -m app.main

Why this helps:

Python treats the code as part of a package
import paths are resolved more consistently
relative import problems are reduced

In some setups, an __init__.py file is also needed to mark a folder as a package.

If you are learning the basics, see how to import a module in Python and sys.path explained.

Fix 5: Look for circular imports

A circular import happens when two files import each other.

Example:

`a.py`

from b import hello_from_b

def hello_from_a():
    return "Hello from A"

print(hello_from_b())

`b.py`

from a import hello_from_a

def hello_from_b():
    return hello_from_a()

This can fail because one module is only partly loaded when the other tries to use it.

Ways to fix circular imports:

move shared code into a third file
delay an import until inside a function
redesign the module structure so files do not depend on each other directly

For example, moving shared code into common.py is often the cleanest fix.

How to debug ImportError step by step

When you see ImportError, use this checklist.

1. Read the full traceback

Do not stop at the last line.

Look for:

the exact module name
the exact imported name
the file where the problem starts

2. Decide what kind of import problem it is

Ask:

Is Python unable to find the module at all?
Or did Python find the module, but fail to import a name from it?

If the module itself is missing, compare with ModuleNotFoundError: No module named X.

3. Print `sys.path`

This shows where Python is searching for modules.

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

You can also learn more in the Python sys module overview.

4. Check for conflicting filenames

Look in your current folder for files named like real modules:

json.py
random.py
math.py

These can cause confusing import behavior.

5. Test the import in a very small file

Create a separate file with only the import:

import math
print(math.__file__)
print(math.sqrt(25))

Or for another module:

import module_name
print(module_name.__file__)

This helps you see what Python is actually importing.

Some errors look similar but mean different things.

`ModuleNotFoundError`

Python cannot find the module at all.

Example idea:

import package_that_is_not_installed

See ModuleNotFoundError: No module named X.

`ImportError: cannot import name`

Python found the module, but not the name you requested.

Example:

from math import square_root

See ImportError: cannot import name.

`AttributeError: module has no attribute`

The import succeeded, but you used a name that does not exist after importing.

Example:

import math
print(math.square_root(9))

See AttributeError: module has no attribute.

Common causes

Here are the most common reasons for ImportError:

misspelled module name
misspelled imported function or class name
package not installed
wrong virtual environment
local file shadows a real module
circular import between project files
incorrect package or relative import

Useful debugging commands

These commands are often enough to find the problem:

python --version
python -m pip --version
python -m pip list
python -c "import sys; print(sys.path)"
python -c "import module_name; print(module_name.__file__)"

What they help you check:

which Python version is running
which pip belongs to that Python
which packages are installed
where Python searches for modules
which file Python actually imported

FAQ

What is the difference between ImportError and ModuleNotFoundError?

ModuleNotFoundError means Python could not find the module.

ImportError is broader and can also happen when a module is found but a requested name cannot be imported.

Why does my import work in one editor but not another?

The editors may be using different Python interpreters or virtual environments.

Can my filename cause ImportError?

Yes. If your file is named like a real module, Python may import your file instead of the intended module.

How do I check where Python is importing from?

Import the module and print module.__file__ to see its location.

Example:

import math
print(math.__file__)