Introduction

Relative imports in Python work only inside packages, and most confusion comes from trying to use them in a file that is being executed as a top-level script. The syntax itself is simple. The tricky part is understanding how Python decides whether a module belongs to a package at import time.

What Relative Imports Mean

Relative imports use leading dots to describe a path relative to the current module.

from .helpers import parse_config
from ..common.logging import get_logger

The rules are:

• '. means the current package'
• '.. means the parent package'
• '... means go up another level'

These imports are resolved from the module's package name, not from the current working directory.

They Work Only Inside Packages

Suppose you have this structure:

1project/
2    app/
3        __init__.py
4        main.py
5        helpers.py

Inside main.py, this is valid:

from .helpers import parse_config

But it works only if main.py is imported or executed as part of the app package. If you run the file directly with python app/main.py, Python treats it as a top-level script, so it has no package context and the relative import fails.

Run Package Modules with -m

The usual fix is to run the module through Python's module mode.

python -m app.main

That tells Python to load app.main as part of the app package, which gives relative imports the package context they need.

This is the key rule that explains most "attempted relative import with no known parent package" errors.

Prefer Absolute Imports at Package Boundaries

Relative imports are useful inside a package, but they are not always the clearest option. Absolute imports are often easier to read in larger projects.

from app.helpers import parse_config

A practical rule is:

• use relative imports for nearby internal modules when that improves locality
• use absolute imports when clarity matters more than brevity

Both can be valid. The important part is to keep the package structure coherent.

Avoid sys.path Hacks

A common but weak workaround is to modify sys.path so direct script execution can find siblings.

1import sys
2from pathlib import Path
3
4sys.path.append(str(Path(__file__).resolve().parent))

This may seem to fix the import error, but it makes the project more fragile and environment-dependent. In most cases, it is better to structure the code as a package and run it with python -m ....

Example Package Layout

Here is a small package that uses relative imports cleanly.

1project/
2    mypkg/
3        __init__.py
4        cli.py
5        utils.py

utils.py:

def format_name(name: str) -> str:
    return name.strip().title()

cli.py:

1from .utils import format_name
2
3
4def main():
5    print(format_name("  alice smith  "))
6
7
8if __name__ == "__main__":
9    main()

Run it like this:

python -m mypkg.cli

That preserves the package context and keeps the relative import valid.

Common Pitfalls

• Running a package module directly as a script and expecting relative imports to work.
• Confusing the current working directory with the module's package path.
• Using sys.path manipulation as a permanent fix instead of structuring the project properly.
• Mixing absolute and relative imports inconsistently until the package layout becomes hard to reason about.
• Forgetting that relative imports only make sense for code that is part of a package.

Summary

• Relative imports use leading dots to refer to modules inside the same package hierarchy.
• They work only when Python knows the current module belongs to a package.
• Run package modules with python -m package.module instead of executing the file directly.
• Prefer a clean package structure over sys.path hacks.
• Use absolute or relative imports deliberately based on readability and package design.