ImportError: cannot import name (circular import, tested)

ImportError: cannot import name 'X' from 'Y' has three common causes. We reproduced each on Python 3.13.5 and found that for the most common one, a circular import, the new error hint points you at the wrong problem.

1. Circular import — and a misleading hint on Python 3.13

mkdir -p demo1 && cd demo1
cat > models.py <<'PY'
from services import save
class User:
    pass
PY
cat > services.py <<'PY'
from models import User
def save(u: User):
    return "saved"
PY
python3 -c "import models"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import models
  File "/tmp/ci/demo1/models.py", line 1, in <module>
    from services import save
  File "/tmp/ci/demo1/services.py", line 1, in <module>
    from models import User
ImportError: cannot import name 'User' from 'models' (consider renaming '/tmp/ci/demo1/models.py' if it has the same name as a library you intended to import)

Measured: models starts running, imports services, which asks models for User — but models is only on line 1, so User doesn't exist yet. The hint most answers online describe is (most likely due to a circular import), from earlier versions (we tested 3.13.5 only). On 3.13.5 we got consider renaming '.../models.py' if it has the same name as a library you intended to import instead, a hint for a different problem (section 2). Nothing here shadows a library: if the traceback shows two of your files importing each other, it's circular, whatever the hint says.

Fix: import the module, not the name (or move the shared code)

mkdir -p demo2 && cd demo2
cat > models.py <<'PY'
import services
class User:
    pass
PY
cat > services.py <<'PY'
import models
def save(u):
    return f"saved {type(u).__name__}"
PY
python3 -c "import models; print(models.services.save(models.User()))"

saved User

Measured: with import services / import models and attribute access at call time (models.services.save), the same two-file cycle works, because neither file needs the other's names while it is still loading. Other fixes: move the shared class into a third module both import; move the import inside the function that uses it; for type hints only, use from __future__ import annotations plus if typing.TYPE_CHECKING: around the import.

2. Your file has the same name as a library

mkdir -p demo3 && cd demo3
cat > json.py <<'PY'
print("this is my json.py")
PY
python3 -c "from json import loads" 2>&1 | tail -1
cat > requests.py <<'PY'
import requests
requests.get
PY
python3 requests.py 2>&1 | tail -1

ImportError: cannot import name 'loads' from 'json' (consider renaming '/tmp/ci/demo3/json.py' since it has the same name as the standard library module named 'json' and prevents importing that standard library module)
AttributeError: module 'requests' has no attribute 'get' (consider renaming '/tmp/ci/demo3/requests.py' if it has the same name as a library you intended to import)

Measured: a json.py in the current directory is imported instead of the standard library json, so loads isn't there. Python 3.13 names the file and says it shadows the standard library. A requests.py that imports requests imports itself, giving AttributeError: module 'requests' has no attribute 'get' with the same renaming hint. Rename the file (and delete any __pycache__ next to it).

3. The name simply isn't there

mkdir -p demo4 && cd demo4
cat > helpers.py <<'PY'
def slugify(s):
    return s.lower()
PY
python3 -c "from helpers import slugfy" 2>&1 | tail -1

ImportError: cannot import name 'slugfy' from 'helpers' (/tmp/ci/demo4/helpers.py). Did you mean: 'slugify'?

Measured: a typo gets a Did you mean suggestion on 3.13. With no suggestion, check the library version: the name may have been renamed or removed in the version you have installed (pip show package), or it lives in a submodule.

Written with AI assistance. Measured on 2026-10-09 with Python 3.13.5: a two-file circular import with from-imports and with plain module imports, local json.py and requests.py files shadowing libraries, and a misspelled name. Every shell block was run verbatim and its output pasted from that run. PlainHeaders is our extension; everything else here is built-in Python.