How to Fix: ImportError: cannot import name ‘X’ from ‘Y’

This error means Python found the file you wanted to import from, but it couldn’t find the specific function or class you asked for.

# WRONG — circular import: file_a.py imports file_b.py, file_b.py imports file_a.py
# file_a.py
from file_b import helper     # ImportError: cannot import name 'helper'

# file_b.py
from file_a import main       # file_a.py is still loading — Python gets stuck

# FIX — move shared code to a third file (shared.py), import from there
# shared.py
def helper(): ...
def main(): ...

# file_a.py
from shared import helper     # works

# file_b.py
from shared import main       # works

# WRONG — you named your file email.py, random.py, math.py, or csv.py
# Python imports YOUR file instead of the standard library

# FIX — rename your file, then delete __pycache__ and any .pyc files
# my_email_script.py          # safe name, no conflict

Cause 1: Circular Imports (The “Chicken and Egg” Problem)

File A tries to import File B, but File B is also trying to import File A. This situation often leads to an ImportError because Python cannot resolve the order in which to import names. Python gets stuck in an infinite loop and crashes.

The Fix: Re-structure your code. Often, you can move the shared code into a third file (File C) and have both A and B import from C.

Cause 2: Shadowing Standard Libraries (Common Beginner Mistake!)

Did you name your own file email.py? If you do, and then try to run import email (hoping to get Python’s standard library), you may encounter an ImportError. Python will import YOUR file instead!

Since your file doesn’t have all the complex tools the real library has, it will fail when you try to use them and result in an ImportError since it cannot import the name you expected.

The Fix: NEVER name your files the same as standard Python modules. Avoid names like:

• email.py
• random.py
• math.py
• csv.py

Rename your file to something else (e.g., my_email_script.py) to prevent ImportError. Also, delete any .pyc files or __pycache__ folders that were created.

ImportError: cannot import name ‘X’ from ‘Y’ — Two Root Causes, Two Permanent Fixes

ImportError: cannot import name ‘X’ from ‘Y’ has exactly two causes. Identify yours in under 60 seconds.

Check your file names first. Open your project folder and look for any .py file named after a Python standard library module: email.py, random.py, math.py, csv.py, os.py, json.py, string.py. Rename the file immediately. Then delete the pycache folder and every .pyc file in your project directory. Python caches the bad import and keeps using it until you clear the cache — renaming alone is not enough.

Check your import graph second. If your file names are clean and the error persists, you have a circular import. File A imports from File B while File B imports from File A — Python loads A, starts loading B, hits the import back to A, and finds A half-loaded. The function or class you’re trying to import doesn’t exist yet.

Fix circular imports by extracting shared code into a third file. Move whatever both files need — utility functions, constants, base classes — into shared.py or utils.py. Both A and B import from that file. Neither imports from each other.

One rule prevents both causes permanently: name every file after what it does, not after what it uses. A file that sends emails is emailer.py, not email.py. A file that processes CSV data is csv_processor.py, not csv.py. Follow that rule and neither of these errors appears again.