Skip to main content

How to Resolve "ImportError: attempted relative import with no known parent package" in Python

When developing Python applications with multiple files, you might encounter the ImportError: attempted relative import with no known parent package. This error arises when you try to use a relative import (e.g., from .module import func) in a script that Python is not treating as part of a package. This typically happens when you run a file directly from the command line that was intended to be part of a larger package structure.

This guide will explain why this ImportError occurs by demonstrating two common scenarios and providing the correct solutions, which involve either adjusting your import statement or, more robustly, changing how you execute your script.

Understanding the Error: Packages vs. Top-Level Scripts​

A Python package is a collection of modules within a directory structure. For a file to use a relative import (like from .helper import ...), it must be recognized by Python as being inside a package.

When you run a script directly, like python my_script.py, Python sets that script's internal name (__name__) to "__main__". In this mode, the script is considered a top-level script and has no knowledge of a "parent package," so relative imports like . or .. have no context and fail.

The ImportError is Python's way of telling you, "You've asked me to go up one level, but I don't know what package I'm in to begin with".

Scenario 1: Importing a Module in the Same Directory​

Let's assume the following project structure:

.
└── project/
    ├── helper.py
    └── main.py

The helper.py file contains a simple function:

# project/helper.py
def greet():
    print("Hello World!")

Example of the code causing the error In main.py, you attempt a relative import to get the greet function.

# project/main.py
from .helper import greet

print("Starting..")
greet()

When you run main.py directly from within the project directory, you get the error:

# Run from inside the 'project' directory
python main.py

Output:

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    from .helper import greet
ImportError: attempted relative import with no known parent package

Solution: Change to an Absolute Import​

For simple cases where both scripts are in the same directory, the easiest fix is to change the relative import to an absolute one. Python automatically includes the script's current directory in its search path.

Solution with Absolute Import:

# project/main.py
from helper import greet # Removed the leading dot

print("Starting..")
greet()
# Run from inside the 'project' directory
python main.py

Output:

Starting..
Hello World!
note

This solution is best for simple scripts. For complex projects that are intended to be installed as packages, the next solution is preferred.

Solution: Run the Script as a Module​

The more robust solution is to tell Python to treat your project directory as a package by running your script using the -m flag. This flag tells Python to run a module from its path.

Solution with -m Flag:

# Run from the parent directory of 'project'
python -m project.main

# Output:
# Starting..
# Hello World!
note

Important: You must run this command from the directory containing the project directory (the parent directory).

In this case, the main.py file remains unchanged (it still uses from .helper import greet). By running it as a module, Python recognizes project as the parent package, giving the relative import the context it needs to resolve .helper.

Scenario 2: Importing from a Sibling Directory​

The error becomes more common in complex structures, such as when importing from a sibling directory.

.
└── project/
    ├── lib/
    │   └── helper.py
    └── src/
        └── main.py

Here, main.py tries to import helper.py using .. to go up one level from src to project and then down into lib.

Example of code causing the error:

# project/src/main.py
from ..lib.helper import greet

print("Starting...")
greet()

Running this script directly will fail, no matter which directory you are in.

# Run from inside the 'project/src' directory
python main.py

Output:

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    from ..lib.helper import greet
ImportError: attempted relative import with no known parent package

Solution: Run the Script as a Module from the Top Level​

As before, the correct solution is to run the script as a module from the top-level directory (the one containing project). This makes the entire project directory a known package to Python.

Solution with -m Flag:

# Run from the parent directory of 'project'
python -m project.src.main

Output:

Starting...
Hello World!

When executed this way, Python understands that project.src.main is part of the project package. The relative import ..lib.helper is resolved correctly: from src, .. goes up to project, and Python can then successfully navigate to lib/helper.py.

Conclusion​

The ImportError: attempted relative import with no known parent package is an error related to execution context, not just code. To resolve it:

  1. For simple, co-located scripts, you can switch from a relative import (from .helper import ...) to an absolute one (from helper import ...).
  2. For any project intended to be a package, keep the relative imports and run your main script as a module using the -m flag from the project's root directory (e.g., python -m package.main). This is the standard and most scalable practice for developing Python applications.

Table of Contents