Attempted Relative Import With No Known Parent Package (Fix)

ImportError: attempted relative import with no known parent package means you ran a file that uses a relative import, like from ..utils import money, directly as a script. Run it as a module from the project root instead:

python -m inventory.reports.summary     # not: python inventory\reports\summary.py

I reproduced the error and every fix in a tiny warehouse project on Windows with Python 3.12.5.

We’ll see why Python has no parent package, fix it with python -m, look at the related “beyond top-level package” error, and set up an entry script that avoids the problem.

The project layout

warehouse/
    main.py
    inventory/
        __init__.py
        utils.py
        reports/
            __init__.py
            summary.py

summary.py uses from ..utils import money: the two dots mean “go up one package from reports to inventory“.

Why you get “attempted relative import with no known parent package”

Relative imports are resolved from __package__. When you run a file by its path, Python names it __main__ and sets __package__ to None, so there’s nothing to go up from:

# inventory\reports\summary.py
print(f"__name__ = {__name__!r}, __package__ = {__package__!r}")
from ..utils import money                 # relative import: go up to inventory, then utils

def build():
    return [("Austin", 1250.50), ("Denver", 980.25), ("Tampa", 1120.75)]

if __name__ == "__main__":
    for city, amount in build():
        print(f"{city:<8}{money(amount):>10}")

# Command Prompt, in C:\pyguides\warehouse
python inventory\reports\summary.py

Output:

__name__ = '__main__', __package__ = None
Traceback (most recent call last):
  File "C:\pyguides\warehouse\inventory\reports\summary.py", line 2, in <module>
    from ..utils import money                 # relative import: go up to inventory, then utils
    ^^^^^^^^^^^^^^^^^^^^^^^^^
ImportError: attempted relative import with no known parent package
Command Prompt showing ImportError attempted relative import with no known parent package after running a Python file by its path
__package__ is None, so ..utils has no parent to start from.

The folders are packages, but Python doesn’t know that because you started at the file, not the package. For the wider set of import fixes, see import from another directory in Python.

Fix it with python -m from the project root

python -m takes a dotted module name. Python imports inventory and inventory.reports first, so the relative import has a parent:

# inventory\utils.py
def money(amount):
    return f"${amount:,.2f}"

# Command Prompt, in C:\pyguides\warehouse
python -m inventory.reports.summary

Output:

__name__ = '__main__', __package__ = 'inventory.reports'
Austin   $1,250.50
Denver     $980.25
Tampa    $1,120.75
Command Prompt output of python -m inventory.reports.summary running successfully with __package__ set to inventory.reports
Same file, no error: __package__ is now 'inventory.reports'.

Two details trip people up. Run it from warehouse, the folder above the package, and leave off the .py extension.

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

This cousin of the error shows up when you run -m from inside the package. Now reports is the top level, and .. tries to climb above it:

# inventory\__init__.py
# inventory/__init__.py marks this folder as a package

# Command Prompt, in C:\pyguides\warehouse
cd inventory && python -m reports.summary

Output:

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\pyguides\warehouse\inventory\reports\summary.py", line 2, in <module>
    from ..utils import money                 # relative import: go up to inventory, then utils
    ^^^^^^^^^^^^^^^^^^^^^^^^^
ImportError: attempted relative import beyond top-level package
__name__ = '__main__', __package__ = 'reports'
Command Prompt showing ImportError attempted relative import beyond top-level package when running python -m from inside the package folder
Started one folder too deep, so inventory isn’t part of the package path.

The fix is the same: change back to the project root and use the full dotted name.

Use an entry script with absolute imports

For apps, I like a small main.py at the project root. Running it puts the root on sys.path, so absolute imports like from inventory.utils import money just work:

# main.py
from inventory.reports.summary import build      # absolute import from the project root
from inventory.utils import money

total = sum(amount for _city, amount in build())
print("Total sales:", money(total))

# Command Prompt, in C:\pyguides\warehouse
python main.py

Output:

__name__ = 'inventory.reports.summary', __package__ = 'inventory.reports'
Total sales: $3,351.50
Command Prompt output of a Python main.py entry script at the project root importing a package with absolute imports
The root script imports summary, whose relative import works because it’s loaded as part of the package.

For bigger projects, a pyproject.toml plus pip install -e . makes the package importable from anywhere; see pip install from pyproject.toml.

Fixing the error in VS Code and PyCharm

  • VS Code: the Run button runs the file as a script. Use a launch configuration with "module": "inventory.reports.summary" instead of "program".
  • PyCharm: in the run configuration, switch from Script path to Module name, and set the working directory to the project root.
  • Either editor: running a root main.py avoids the issue entirely.

Setting up the editor itself is covered in Python extension for VS Code.

Quick fixes at a glance

SituationFix
Ran python path\to\file.pypython -m package.module from the project root
“beyond top-level package”Run from one folder higher, using the full dotted name
App with several packagesRoot main.py with absolute imports
Need imports from anywherepyproject.toml + pip install -e .
IDE run button failsRun configuration set to a module, not a script

You might also find these guides useful:

Frequently asked questions

What does attempted relative import with no known parent package mean?

You ran a file with a relative import directly, so Python set __package__ to None and can’t tell which package the dots refer to.

How do I fix it quickly?

From the project root, run python -m package.module without the .py extension.

Should I use absolute or relative imports?

Both work inside packages. Absolute imports are clearer and also work from a root entry script; PEP 8 recommends them.

Does adding __init__.py fix it?

Not by itself. The folders need to be packages, but you still have to run the code as a module or import it from outside.

Why do I get beyond top-level package?

You ran -m from inside the package, so the relative import tries to climb above the top package. Run it from one folder higher.

Where are relative imports documented?

See Intra-package References in the Python tutorial.