ImportError: cannot import name (Fix)

If you see the Python error ImportError: cannot import name ..., Python was able to find the module, but it could not find the specific function, class, or variable you asked for.

This usually happens because:

  • the name is spelled wrong
  • you imported from the wrong module
  • the name is not available at the top level
  • there is a circular import
  • a local file is conflicting with a real module

This guide shows how to find the cause and fix it.

Quick fix

# Check that the name really exists in the module
from mymodule import my_function

# Alternative: import the module first, then inspect it
import mymodule
print(dir(mymodule))

# Then access the name with dot notation if it exists
mymodule.my_function()

This error usually means the name does not exist, is spelled wrong, is defined in the wrong file, or there is a circular import.

What this error means

ImportError: cannot import name means:

  • Python found the module
  • but Python could not find the specific name inside that module

For example, this can fail:

from math import square

because the math module exists, but it does not provide a name called square.

This is different from ModuleNotFoundError: no module named x, where Python cannot find the module at all.

Common example that causes the error

A simple example:

from math import square

Expected result:

ImportError: cannot import name 'square' from 'math'

Why this fails:

  • math is a real module
  • but square is not a function in math

A correct version would be:

import math

print(math.sqrt(16))

Output:

4.0

Other common cases:

  • you try to import a function that was renamed or deleted
  • you import from the wrong file with a similar name
  • you copy example code written for a different package version

Why it happens

Here are the most common reasons:

  • Misspelled name
    You wrote my_fuction instead of my_function.
  • Wrong module
    The name exists, but in a different module.
  • Name is not at the top level
    The value may only be created inside a function, loop, or if block.
  • Circular import
    Two files import from each other before loading is complete.
  • Local file conflict
    A file in your project has the same name as a standard library module or installed package.
  • Package version changed
    The example you copied may use an older or newer API.

If you are not comfortable with how imports work, see how import works in Python and how to import a module in Python.

How to fix it

Try these fixes in order:

  1. Check the spelling
    • Compare the imported name with the real name in the module.
  2. Open the module
    • Confirm the function, class, or variable actually exists.
  3. Import the module first
    • Then inspect it with dir().
  4. Make sure the module is the correct one
    • You may be importing a different file than you think.
  5. Rename conflicting local files
    • Files like random.py, json.py, or os.py often cause problems.
  6. Fix circular imports
    • Move shared code into a third file, or move imports inside functions when appropriate.
  7. Check package documentation
    • The name may have moved or been removed in your installed version.

Example using dir():

import math

print("square" in dir(math))
print("sqrt" in dir(math))

Output:

False
True

You can learn more about this with the Python dir() function explained.

Circular import case

A circular import happens when two files depend on each other while Python is still loading them.

Example:

a.py

from b import greet_b

def greet_a():
    return "Hello from A"

b.py

from a import greet_a

def greet_b():
    return "Hello from B"

This setup can fail because:

  • a.py starts importing b.py
  • b.py then tries to import from a.py
  • but a.py has not finished loading yet

A common error looks like this:

ImportError: cannot import name 'greet_a' from partially initialized module 'a'

Common fixes:

  • move the import inside a function
  • move shared code into a third file
  • restructure the files so only one depends on the other

For example, moving shared code to common.py often fixes the problem.

How to debug step by step

Use this process when you are stuck.

1. Read the full traceback

Look for:

  • the module name
  • the imported name
  • the file path Python is using

2. Open the target module

Search for the missing name.

Make sure it is really defined, and spelled the same way.

3. Check which file Python imported

import mymodule
print(mymodule.__file__)

This shows the actual file path Python loaded.

That helps you catch problems where you are importing the wrong file.

4. List the names in the module

import mymodule
print(dir(mymodule))

If your name is missing from the list, Python cannot import it from that module.

5. Look for local filename conflicts

Check your project folder for files like:

  • random.py
  • json.py
  • os.py
  • math.py

These can shadow the real modules.

For example, if you create a file named math.py, then this import may not use the real standard library module.

6. Check for circular imports

Look for two files importing each other.

If file A imports from file B, and file B imports from file A, that is a strong sign of a circular import.

Common causes

These are the most common causes of this error:

  • Misspelled imported name
  • Wrong module path
  • Circular import
  • Local file name conflict
  • Outdated example code for a newer package version
  • Trying to import a name that is created only inside a function or condition

Here is an example of a name that cannot be imported because it is not defined at the top level:

# mymodule.py

def make_value():
    hidden_value = 10
    return hidden_value

This will fail:

from mymodule import hidden_value

because hidden_value only exists inside the function.

A correct version would be:

from mymodule import make_value

print(make_value())

Output:

10

Useful debugging commands

These commands are helpful when tracking down the problem:

import mymodule; print(mymodule.__file__)
import mymodule; print(dir(mymodule))
help(mymodule)

From the command line:

python --version
pip show package_name

What they help with:

  • mymodule.__file__ shows which file Python imported
  • dir(mymodule) shows the names available in the module
  • help(mymodule) gives basic module information
  • python --version helps confirm your Python version
  • pip show package_name shows the installed package version

FAQ

What is the difference between ImportError and ModuleNotFoundError?

ModuleNotFoundError means Python cannot find the module.

ImportError: cannot import name means Python found the module but not the specific name inside it.

Can circular imports cause this error?

Yes. If two files import each other, one file may try to import a name before it is available.

Why does this happen even though the name is in the file?

Common reasons:

  • you are importing the wrong file
  • a local filename is conflicting with the real module
  • there is a circular import
  • the name is not available when the import runs

How do I check what names a module provides?

Import the module and use dir(module_name) to list the available names.

Example:

import math
print(dir(math))

See also