Python Relative Imports in Packages: Syntax, Errors, and Fixes
Understand how relative imports work inside Python packages, why they fail when run directly, and how to structure modules for reliable imports.

Relative imports in Python let a package import its own modules using a leading dot, but they often fail with confusing errors when the module is run directly. This article explains how relative imports work inside Python packages, why they break, and how to structure your code to use them reliably.
What Are Relative Imports in Python Packages?
Relative imports are imports that resolve relative to the current module's package. They use leading dots to indicate the current package (one dot) or parent packages (two or more dots). For example, inside a module in mypackage/submodule.py, from . import sibling imports mypackage.sibling. This works only when the module is part of a package and the package is loaded in a way that Python recognizes its parent.
Relative Import Syntax and How It Resolves
The syntax is straightforward: a single dot refers to the current package, two dots to the parent package, and so on. For example:
from . import module_in_same_package
from .. import module_in_parent_package
from .subpackage import module_in_subpackagePython resolves these relative to the __package__ attribute of the module. When a module is imported as part of a package, __package__ is set to the package name, allowing relative imports to work. The resolution is based on the module's __package__ value, not the filesystem path.
Why Relative Imports Fail: No Known Parent Package Error
The most common error is ImportError: attempted relative import with no known parent package. This happens when you run a module directly as a script, like python mypackage/submodule.py. In that case, Python treats the module as the top-level script and sets __package__ to None, so relative imports have no package context to resolve against.
The same error occurs if you run a script inside a package without using the -m flag. In older Python versions, a missing __init__.py file could also prevent the directory from being recognized as a package. Python 3.3+ supports namespace packages without __init__.py, but relative imports still depend on how the module is invoked.
Running Modules as Scripts vs. Using python -m
To run a module as part of its package, use the module path with -m:
python -m mypackage.submoduleThis sets __package__ correctly and allows relative imports to resolve. The -m flag tells Python to import the module rather than execute the file as a script. This is the standard way to run a module that relies on relative imports.
If you need to run a file directly for debugging, avoid trying to work around the package context by adjusting __package__ or relying on PYTHONPATH alone. Use python -m instead, or temporarily switch to absolute imports. An entry-point script at the project root is another way to invoke the code with the package context intact.
Practical Package Structure for Reliable Relative Imports
A typical package layout that works well with relative imports:
project/
mypackage/
__init__.py
main.py
helpers.py
subpackage/
__init__.py
utils.pyInside main.py, you can write:
from . import helpers
from .subpackage import utilsTo run main.py, use:
python -m mypackage.mainThis works because the -m flag sets __package__ to mypackage, and the relative imports resolve accordingly.
When to Prefer Absolute Imports Over Relative Imports
Relative imports keep module references concise and make it clear that a module belongs to the same package. However, they can be confusing when the package is deeply nested, and they make it harder to move modules between packages. Absolute imports, such as from mypackage.subpackage import utils, are explicit and work regardless of how the module is invoked, as long as the package is on sys.path. Many projects adopt absolute imports for readability and to avoid the 'no known parent package' trap.
The choice depends on your project's structure and team conventions. If you control the entry points and always run with -m, relative imports are safe. If your code may be executed as scripts or embedded in other contexts, absolute imports are more robust.
Compatibility and Maintainability Considerations
In modern Python 3, absolute imports are the default behavior, and explicit relative imports are available with leading dots. They rely on the module's __package__ being set correctly, which depends on how the module is loaded. This makes relative imports sensitive to execution context.
For maintainability, keep the package structure shallow and use python -m consistently in documentation and scripts. Avoid mixing relative and absolute imports in the same package, as that can confuse readers. Renaming a package is easier with relative imports inside that package, because the dot syntax refers to the current package by position rather than by name. Absolute imports require updating the package name in every import statement.
When you need to run a module directly during development, consider adding a small entry-point script at the project root that imports and calls the package module, rather than executing the module file directly. This keeps the package context intact and avoids the common error.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.