Running a Python Module Directly

The most common cause is executing a package module as a standalone script.

Consider this structure:

project/

│
└── mypackage/
├── __init__.py
├── main.py
└── utils.py

Inside main.py:

Python

Run
from .utils import helper
helper()

Running the following command from the project directory can produce the error:

Bash
python mypackage/main.py

Python executes the file as __main__, without establishing mypackage as its parent package.

So Python can’t resolve the relative import.

Incorrect Package Structure

Another cause is organizing modules without considering how Python discovers packages.

For example:

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

Using:

Python

Run
from .utils import helper

inside a directly executed main.py does not work because the file has no known parent package.

Although Python supports namespace packages without __init__.py, adding that file can make conventional package structures clearer.

However, adding __init__.py alone does not fix direct execution of a module containing relative imports.

Incorrect Import Statements

Developers sometimes use relative imports when absolute imports would be more appropriate.

For example:

Python

Run
from ..services import database

This statement attempts to access a module through the parent package.

If the module isn’t imported within the expected package hierarchy, Python cannot resolve the reference.

The number of leading dots must also match the actual package structure.

Running Scripts From the Wrong Directory

The working directory affects which modules Python can discover through its import search path.

Running a project from an unexpected location may cause package resolution problems or produce a related ModuleNotFoundError.

For package-based applications, executing modules from the correct project root is often essential.

Fix 1: Run the Module Using the -m Option

One of the most reliable solutions is to execute the module as part of its package.

Consider:

project/
│
└── mypackage/
├── __init__.py
├── main.py
└── utils.py

Inside utils.py:

Python

Run
def helper():
print("Helper function executed")

Inside main.py:

Python

Run
from .utils import helper
helper()

Instead of running:

Bash

python mypackage/main.py

navigate to the project root and execute:

Bash

python -m mypackage.main

Output:

Helper function executed

The -m option instructs Python to locate and execute the module through the import system.

This establishes the correct package context, allowing relative imports to work.

For existing package modules, this is often the simplest fix.

Fix 2: Use Absolute Imports

Another solution is replacing relative imports with absolute imports.

For example, change:

Python

Run
from .utils import helper

to:

Python

Run

from mypackage.utils import helper

The absolute import specifies the complete module path.

With the same project structure, run the application from the project root:

Bash

python -m mypackage.main

Absolute imports are generally easier to understand in larger applications because they clearly identify the package containing each module.

However, Python must still be able to discover the package through its import path.

Simply changing to an absolute import does not guarantee that executing a nested script directly will work.

Fix 3: Organize the Project as a Python Package

A clear package structure makes module imports easier to maintain.

For example:

project/
│
├── mypackage/
│   ├── __init__.py
│   ├── main.py
│   ├── services/
│   │   ├── __init__.py
│   │   └── database.py
│   └── utils/
│       ├── __init__.py
│       └── helpers.py
│
└── tests/

Inside main.py, an absolute import might look like:

Python

Run

from mypackage.utils.helpers import helper

Alternatively, a relative import could be:

Python

Run

from .utils.helpers import helper

Both approaches can work when Python executes or imports the module within the appropriate package context.

Using a consistent package layout helps prevent import errors as applications grow.

Fix 4: Check the init.py File

The __init__.py file traditionally identifies a directory as a regular Python package.

For example:

mypackage/
├── __init__.py
├── main.py
└── utils.py

The file can be empty:

Python

Run
# Package initialization

Python also supports namespace packages without this file, so it is not universally mandatory.

Nevertheless, including __init__.py helps with conventional package layouts and can reduce ambiguity in some tools and development environments.

Remember that package initialization and execution context are separate concerns. A relative import can still fail when you run a package module directly by its filename.

Fix 5: Create a Separate Entry-Point Script

If an application needs a directly executable script, keep that script outside the package and use absolute imports.

Example:

project/
├── run.py
└── mypackage/
├── __init__.py
├── main.py
└── utils.py

Inside main.py:

Python

Run
from .utils import helper
def start():
helper()

Inside run.py:

Python

Run
from mypackage.main import start
if __name__ == "__main__":
start()

Run the application from the project root:

Bash
python run.py

Because run.py imports mypackage.main through its package name, the relative import inside main.py can resolve correctly.

This approach separates application startup from internal package functionality.

Visual Studio Code

In VS Code, configure the debugger to execute the module rather than its file path.

For example, a launch.json configuration can include:

JSON

{
"version": "0.2.0",
"configurations": [
{
"name": "Run Python Module",
"type": "debugpy",
"request": "launch",
"module": "mypackage.main",
"cwd": "${workspaceFolder}"
}
]
}

This configuration runs the module within its package context.

PyCharm

In PyCharm, create or edit a Python run configuration.

Select the module-based execution option, specify the qualified module name, and ensure the working directory and interpreter are set up correctly.

For example, execute:

mypackage.main

rather than directly launching the nested main.py file.