ImportError: attempted relative import with no known parent package (tested)

ImportError: attempted relative import with no known parent package means a file using from .x import y was run directly. We ran the same package seven ways on Python 3.13.5 to show which launches work.

1. Running a package file as a script

Layout: proj/app/__init__.py (empty), proj/app/helpers.py with a greet() function, and proj/app/main.py:

from .helpers import greet

print(__name__, __package__, greet())

$ cd proj && python3 app/main.py
Traceback (most recent call last):
  File "/tmp/ri/proj/app/main.py", line 1, in <module>
    from .helpers import greet
ImportError: attempted relative import with no known parent package

Measured on Python 3.13.5: running a file by path makes it __main__ with no package, so .helpers has nothing to be relative to. The __init__.py being there doesn't matter.

2. Fix: run it as a module from the project root

$ cd proj && python3 -m app.main
__main__ app hi from helpers

Measured: with -m app.main, __package__ is app and the relative import works. Note the dots, not slashes, and no .py. Where you run it from matters:

$ cd proj/app && python3 -m main
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/tmp/ri/proj/app/main.py", line 1, in <module>
    from .helpers import greet
ImportError: attempted relative import with no known parent package

$ cd proj && python3 -m app/main.py
/usr/bin/python3: Error while finding module specification for 'app/main.py' (ModuleNotFoundError: No module named 'app/main'). Try using 'app/main' instead of 'app/main.py' as the module name.

Measured: from inside app/, -m main gives the same ImportError, because main is now a top-level module. With a path-style name, Python's own hint suggests 'app/main', and we ran that too: it fails with No module named app/main. The working form is python3 -m app.main from proj/.

3. The “just remove the dot” fix breaks the other way

Changing the import to from helpers import greet (no dot) and running both ways:

$ python3 app/main.py
hi from helpers
$ python3 -m app.main
ModuleNotFoundError: No module named 'helpers'

Measured: it works as a script (the script's folder is put on sys.path) and fails as a module. So it moves the error rather than fixing it. Prefer -m with relative imports, or absolute imports from the package root (from app.helpers import greet) plus -m.

4. Two related cases

No __init__.py: we removed it and ran python3 -m pkg.main: it worked (output pkg hi). A missing __init__.py isn't the cause on Python 3; how you launch the file is.
Too many dots: from ...helpers import greet in app/sub/deep.py, run with -m app.sub.deep, gave ImportError: attempted relative import beyond top-level package. Each dot goes up one package; ... from app.sub goes above app.

Frequently asked questions

How do I fix attempted relative import with no known parent package?

Run the file as a module from the project root: python3 -m app.main instead of python3 app/main.py. We measured the same file failing one way and working the other.

Does adding __init__.py fix the relative import error?

No. We measured the error with __init__.py present, and -m working without it. The cause is running the file directly, which gives it no parent package.

Why does removing the dot from the import break python -m?

from helpers import works as a script because the script's folder is on sys.path, but under -m only the project root is, so we measured ModuleNotFoundError: No module named 'helpers'.

What does attempted relative import beyond top-level package mean?

The import has more dots than there are package levels above the module. We measured it with from ...helpers inside app/sub/deep.py.

Written with AI assistance. Measured on 2026-10-09 with Python 3.13.5 on Linux: one small package run as a script, with -m from the project root and from inside the package, with a path-style -m name, with the dot removed, without __init__.py, and with too many dots. Every command was run verbatim and its output pasted from that run. PlainHeaders is our extension; everything else here is built-in Python.