ImportError: cannot import name (unknown location) (tested)

ImportError: cannot import name 'X' from 'Y' (unknown location) means Python imported a directory named Y as a namespace package, so there was no file to find X in. We reproduced every cause we know of on Python 3.13.5.

1. A folder with no __init__.py

mkdir -p demo1/mypkg && cd demo1
cat > mypkg/utils.py <<'PY'
def helper():
    return "ok"
PY
python3 -c "from mypkg import helper" 2>&1 | tail -1
python3 -c "import mypkg; print(mypkg.__file__, mypkg.__path__)"

Output:

ImportError: cannot import name 'helper' from 'mypkg' (unknown location)
None _NamespacePath(['/tmp/ul3/demo1/mypkg'])

Measured on Python 3.13.5: mypkg/ has no __init__.py, so Python imports it as a namespace package. A namespace package has no file (__file__ is None) and no code of its own, so there is nowhere for helper to come from. That's the "unknown location": Python found a directory called mypkg, not a module. Here helper lives in mypkg/utils.py, which from mypkg import helper never loads.

2. Fix: import from the submodule, or re-export it in __init__.py

mkdir -p demo2/mypkg && cd demo2
cat > mypkg/utils.py <<'PY'
def helper():
    return "ok"
PY
python3 -c "from mypkg.utils import helper; print(helper())"
cat > mypkg/__init__.py <<'PY'
from .utils import helper
PY
python3 -c "from mypkg import helper; print(helper())"

Output:

ok
ok

Measured: both work. from mypkg.utils import helper names the file that defines it. Or add mypkg/__init__.py with from .utils import helper, which makes mypkg a regular package that exposes helper directly.

3. An empty folder hiding the fact that a package isn't installed

mkdir -p demo3/flask demo3/requests && cd demo3
python3 -c "from flask import Flask" 2>&1 | tail -1
python3 -c "import requests; print(requests.__file__)"

Output:

ImportError: cannot import name 'Flask' from 'flask' (unknown location)
/usr/lib/python3/dist-packages/requests/__init__.py

Measured: flask is not installed on our test machine. Without the folder, import flask gives ModuleNotFoundError: No module named 'flask'. With an empty flask/ directory in the current directory, the error changes to cannot import name 'Flask' from 'flask' (unknown location), which hides the real problem. An empty requests/ directory did not shadow the installed requests, because Python only uses a namespace package if it finds no regular package or module with that name anywhere on sys.path. So "unknown location" for a library name usually means the library isn't installed for this Python (check python3 -m pip show flask) and a stray directory with the same name is on the path.

4. Leftovers: a directory with only __pycache__

mkdir -p demo5/libs/mylib/__pycache__ && cd demo5
touch libs/mylib/__pycache__/core.cpython-313.pyc
PYTHONPATH=libs python3 -c "from mylib import Client" 2>&1 | tail -1
PYTHONPATH=libs python3 -c "import mylib, sys; print(mylib.__spec__.origin, list(mylib.__path__))"

Output:

ImportError: cannot import name 'Client' from 'mylib' (unknown location)
None ['/tmp/ul3/demo5/libs/mylib']

Measured: a directory that only contains __pycache__ (what a manual delete or a half-finished uninstall can leave behind) still imports as a namespace package, and gives the same error. The .pyc inside is ignored: __pycache__ files are only used next to their source .py. Print list(mylib.__path__) to find the directory Python actually picked, then delete it or reinstall the package.

5. Same project, different error, depending on how you run it

mkdir -p demo4/app && cd demo4
cat > app/main.py <<'PY'
from app import config
PY
python3 app/main.py 2>&1 | tail -1
python3 -m app.main 2>&1 | tail -1

Output:

ModuleNotFoundError: No module named 'app'
ImportError: cannot import name 'config' from 'app' (unknown location)

Measured: python3 app/main.py puts app/ itself on sys.path, so app isn't found at all (ModuleNotFoundError). python3 -m app.main from the project root finds app/ as a namespace package, and then can't find config in it (unknown location). Here config.py doesn't exist; when it does, from app import config works with -m (the submodule gets imported) even without __init__.py. The error only means the name is neither a submodule file nor defined in the folder (it can't be, since there is no __init__.py).

Quick check

python3 -c "import mypkg; print(mypkg.__file__, list(mypkg.__path__))". If __file__ is None, you've got a namespace package. The path shows which directory Python used.

Written with AI assistance. Measured on 2026-10-09 with Python 3.13.5: a package folder without __init__.py, the submodule and __init__.py fixes, empty flask/ and requests/ folders, a folder containing only __pycache__, and python3 app/main.py vs python3 -m app.main. Every block was run verbatim and its output pasted from that run. PlainHeaders is our extension; everything else here is built-in Python.