Python「attempted relative import with no known parent package」の原因と直し方
attempted relative import with no known parent package は、相対インポートを含むファイルを直接実行すると出る。python -m でパッケージとして実行すれば直る。
公開: 更新:
python mypkg/main.py Traceback (most recent call last): File "/tmp/tmp.RjurFhG5SI/mypkg/main.py", line 1, in <module> from .utils import helper ImportError: attempted relative import with no known parent package
python -m mypkg.main helper called
2026-08-28 に python:3.12(Python 3.12.14) で実際に打って取った出力。検証環境の詳細
要約
ImportError: attempted relative import with no known parent package は、相対インポート(先頭がドットの from . import ...)を、パッケージの一部としてではなく単体スクリプトとして実行したときに出る。
相対インポートはモジュールの __package__ を起点に親パッケージを辿るが、ファイルを直接実行すると __main__ 扱いになり起点が空になるため、親パッケージを特定できない。python -m でパッケージとして実行するのが基本の解決策である。
ImportError: attempted relative import with no known parent package実行例
python:3.12 で python mypkg/main.py のようにパッケージ内のファイルをパス指定で起動すると、attempted relative import with no known parent package が出て終了コード 1 で止まる。
コードを 1 文字も変えずに python -m mypkg.main で起動した場合と、パッケージの外に置いた run.py を入口にした場合は、どちらも helper called を出して 0 で終わる。
$ python --version
Python 3.12.14$ python mypkg/main.py
Traceback (most recent call last):
File "/tmp/tmp.RjurFhG5SI/mypkg/main.py", line 1, in <module>
from .utils import helper
ImportError: attempted relative import with no known parent package
$ echo $?
1$ python -m mypkg.main
helper called
$ echo $?
0$ python run.py
helper called
$ echo $?
0— 2026-08-28 時点の出力
検証環境Python 3.12.14 / Git 2.47.3 / 2026-08-28 検証
- 検証日
- 実行環境
python:3.12Debian GNU/Linux 13 (trixie)- バージョン
- Python 3.12.14
- Git 2.47.3
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. -m でパッケージとして実行する
mypkg/main.py を直接叩かずに、プロジェクトルートからモジュール指定で実行する。
これで __package__ が正しく設定され、相対インポートが解決する。
# NG: python mypkg/main.py
python -m mypkg.mainディレクトリ構成の例を示す。
各パッケージに __init__.py を置く。
project/
mypkg/
__init__.py
main.py
utils.py2. 絶対インポートに書き換える
ドット表記をやめ、パッケージ名から書く絶対インポートにすると、実行方法に左右されにくくなる。
# from .utils import helper →
from mypkg.utils import helper3. エントリポイントを分離する
ライブラリ本体は相対インポートのままにし、起動用のファイルをパッケージの外(または python -m mypkg 用の __main__.py)に置いて、そこからパッケージを呼び出す構成にすると安定する。
よくある原因
- スクリプトとして直接実行している。
python mypkg/main.pyのように単体実行すると、そのファイルは__main__になり相対インポートの基準を失う。 - 実行位置とパッケージ構成が合っていない。
プロジェクトルート以外から実行していて、sys.pathにルートが入っていない。 - エントリポイント自身が相対インポートを使っている。
起動ファイルでドット表記を使うと、起動方法によっては必ず失敗する。