Python Relative Imports Explained: Fixing "attempted relative import with no known parent package"

By the end of this page, you will understand what Python packages are, how relative imports work, why running a module directly often causes import errors, and how to use python -m correctly. You will also see practical examples of package layouts, import syntax, and the most common mistakes that lead to attempted relative import with no known parent package.

In Python, a relative import means importing something based on the current module's position inside a package.

For example:

from . import moduleY
from ..subpackage2 import moduleZ

The dots mean:

• . = current package
• .. = parent package
• ... = grandparent package

For Python to resolve those dots, it must know where the current module lives inside the package hierarchy.

That is the key idea.

If Python runs a file as a plain script, that file is treated as a top-level module, usually with:

__name__ == "__main__"

In that situation, Python does not reliably know the module's package context, so a statement like this cannot be resolved:

from . import moduleY

Python then raises:

ImportError: attempted relative import with no known parent package

What is a package?

Think of a relative import like giving directions inside a building.

• . means "this room"
• .. means "go up one floor"

But those directions only work if you know where you currently are.

If someone drops you in a building and says only, "You are here," then go up one floor makes sense.

But if you are standing in an empty field with no building map, "go up one floor" is meaningless.

That is what happens with Python:

• When a module is run as part of a package, Python has the building map.
• When a file is run directly as a script, Python often loses that map.

So a relative import is like saying:

Go to the sibling room next to me.

Python answers:

I do not know what building you are in, so I cannot follow that instruction.

That is the meaning of no known parent package.

Basic relative import syntax

from . import moduleY
from .moduleY import spam
from ..subpackage2 import moduleZ
from ..subpackage2.moduleZ import eggs

Example package

package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py

Example code

package/subpackage1/moduleY.py

def spam():
    return "spam from moduleY"

package/subpackage1/moduleX.py

from .moduleY import spam

print(spam())

Wrong way to run it

python package/subpackage1/moduleX.py

This often fails because moduleX.py is being run as a standalone script, not as part of .

Consider this file:

package/subpackage1/moduleX.py

from .moduleY import spam

print(spam())

And this file:

package/subpackage1/moduleY.py

def spam():
    return "hello"

Case 1: Run the file directly

python package/subpackage1/moduleX.py

What happens:

1. Python starts executing moduleX.py as a script.
2. Its module name becomes __main__.
3. Python does not treat it as package.subpackage1.moduleX.
4. The line from .moduleY import spam means "import moduleY from my current package".
5. But Python does not know the current package.
6. It raises:

ImportError: attempted relative import  no known parent package

Relative imports are useful when code is organized into packages and subpackages.

Common scenarios

• Utility modules inside a package
  • Example: from .helpers import format_date
• Feature folders in web apps
  • Example: routes importing validators or services from the same package
• Data processing packages
  • One module imports parsers, cleaners, or exporters from nearby modules
• Libraries distributed on PyPI
  • Internal modules often use package-relative imports to reference sibling files

Example: API package

myapp/
    api/
        __init__.py
        routes.py
        validators.py

routes.py might contain:

from .validators import validate_user_payload

This keeps imports tied to the package structure instead of depending on the current working directory.

When relative imports help most

• When modules in the same package need to talk to each other
• When you want to avoid repeating a long absolute path
• When code may be moved within the project without changing every import

In real projects, developers usually combine absolute imports for clarity and relative imports for internal package relationships.

Common patterns

1. Internal helpers

from .utils import parse_config
from .errors import ConfigError

This is common when files are tightly related inside one package.

2. Absolute imports at package boundaries

from myapp.database.connection import connect

This makes it clear where code comes from, especially in larger applications.

3. Guarded script entry points

Instead of running package files directly, developers often add an entry point:

def main():
    print("Run app")

if __name__ == "__main__":
    main()

Then they execute it with:

python -m package.subpackage1.moduleX

4. Separation between library code and runnable code

A common pattern is:

• package modules contain reusable logic

1. Running a package module as a plain script

Broken:

python package/subpackage1/moduleX.py

If moduleX.py contains:

from .moduleY import spam

it may fail because Python does not know its package context.

Avoid it by running:

python -m package.subpackage1.moduleX

2. Forgetting the package root

If you run -m from the wrong directory, Python may not find the package.

Suppose your structure is:

project/
    package/
        __init__.py

You should usually run this from project/, not from inside package/:

python -m package.moduleA

3. Mixing direct execution and package imports

Broken pattern:

# inside moduleX.py
from .moduleY  spam

 __name__ == :
    (spam())

Quick rules

• Relative imports use dots:
  • . current package
  • .. parent package
• Relative imports only work when Python knows the module's package name.
• Running a file directly often removes that package context.
• Use python -m package.module instead of python path/to/file.py for package modules.

Common syntax

from . import moduleY
from .moduleY import spam
from ..subpackage2 import moduleZ
from package.subpackage1.moduleY import spam  # absolute import

Typical package layout

project/
    package/
        __init__.py
        subpackage1/
            __init__.py
            moduleX.py
            moduleY.py

Correct run command

From project/:

python -m package.subpackage1.moduleX

Common error meaning

Why does Python say "attempted relative import with no known parent package"?

Because the module uses a relative import like from .x import y, but Python does not know what package the current file belongs to.

What is a parent package in Python?

It is the package that contains the current module. For example, the parent package of package.subpackage1.moduleX is package.subpackage1.

Why does running a file directly break relative imports?

Because Python usually loads that file as __main__ instead of by its full package name, so the package hierarchy is lost.

How does python -m fix relative imports?

It runs the module by its dotted module name, so Python knows its package context and can resolve relative imports.

Do I always need __init__.py for a package?

In modern Python, not always, because namespace packages exist. But for most beginner learning and many projects, including __init__.py makes package behavior clearer.

Should I use relative or absolute imports?

Use absolute imports when you want clarity and consistency. Use relative imports for nearby internal modules when that makes the package easier to maintain.

Can a top-level script use relative imports?

Usually no. Relative imports are meant for modules inside packages, not standalone scripts.

What is the safest project structure for avoiding this error?

• Python modules — A module is a single Python file, and packages are built from modules.
• Python packages — Relative imports only make sense inside package hierarchies.
• Absolute imports — The main alternative to relative imports.
• __init__.py — Commonly used to mark directories as packages.
• __name__ and __main__ — Important for understanding why direct execution changes import behavior.
• Module search path (sys.path) — Helps explain how Python locates importable modules.
• python -m — The standard way to run a module within its package context.
• Project structure in Python — Good layout decisions prevent import confusion.