ImportError: attempted relative import with no known parent package

Python · updated 2026-11-03

Raised at import time when a module that uses a relative import (from . or from ..) is executed directly with python path/to/file.py. Run that way, the file's __package__ is empty, so the dots have nothing to be relative to.

Traceback (most recent call last):
  File "/app/myapp/jobs/sync.py", line 3, in <module>
    from ..db import session
ImportError: attempted relative import with no known parent package

Quick fix

Run the file as a module from the project root: python -m myapp.jobs.sync instead of python myapp/jobs/sync.py. If the file is meant to be a script, switch its relative imports to absolute ones (from myapp.db import session) and install the project in editable mode.

cd to the folder that contains the top-level package (the one with myapp/ in it).
Run python -m myapp.jobs.sync, using dots instead of slashes and no .py.
For scripts, entry points or cron jobs, prefer absolute imports from the package name.
Install the project with pip install -e . so the package is importable from anywhere.
Make sure each folder in the package path has an __init__.py if you rely on regular packages.

bash

# Fails: run as a script, no parent package
python myapp/jobs/sync.py

# Works: run as a module from the project root
python -m myapp.jobs.sync

# Or make the package importable everywhere (pyproject.toml present)
pip install -e .

Why it happens

Running a module file directly

Editors with a Run button, cron entries and Dockerfile CMD lines often call python path/to/file.py. That runs the file as __main__ with no package, so any from . import fails.

Running from the wrong folder

python -m only finds the package if the current directory (or sys.path) contains it. Running from inside the package folder makes the top-level name unknown.

Tests run from a subfolder

Test runners started in a subdirectory, or with a rootdir that excludes the package, import test files without their package context.

Other fixes

Define console scripts in pyproject.toml ([project.scripts]) so jobs run through an installed entry point instead of a file path.
Avoid editing sys.path in code to work around this: it hides the packaging problem and breaks in other environments.

Same error, other wording

ImportError: attempted relative import beyond top-level package
ModuleNotFoundError: No module named '__main__.db'; '__main__' is not a package

Let your coding agent catch the next one

Runheed records this error in production with the stack trace, the breadcrumbs before it and the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:

> Find where 'attempted relative import with no known parent package' is raised, show me how each of those files is started (cron, Docker CMD, IDE), and change the command to python -m or switch the imports to absolute.

Plans from $29/mo See what your agent reads See the setupCancel any time from the billing portal