できない.dev

pytest でテストから自作モジュールを import できない(ModuleNotFoundError)

pytest はプロジェクトのルートではなく、テストファイル側のディレクトリを sys.path に足す。
src レイアウトなら設定の pythonpath か編集可能インストール、フラットな構成なら python -m pytest か tests/__init__.py で解決する。

公開: 更新:

症状できない · exit 2
pytest -q
…
==================================== ERRORS ====================================
_____________________ ERROR collecting tests/test_calc.py ______________________
ImportError while importing test module '/tmp/tmp.g9O7vLp6X3/tests/test_calc.py'.
Hint: make sure your test modules/packages have valid Python names.
解決後できた · exit 0
pytest -q
.                                                                        [100%]
1 passed in 0.00s

2026-10-24 に python:3.12(pytest 8.4.2) で実際に打って取った出力。検証環境の詳細

要約

アプリのコードは python から普通に動くのに、pytest でテストを実行すると収集の段階で止まる。

ImportError while importing test module '/app/tests/test_calc.py'.
Hint: make sure your test modules/packages have valid Python names.
...
E   ModuleNotFoundError: No module named 'myapp'

pytest は既定の import モード(prepend)で、テストファイルから上へたどって最初に __init__.py が無いディレクトリを sys.path の先頭に足す。
tests/ に __init__.py が無ければ、足されるのは tests/ だけで、プロジェクトのルートや src/ は入らない。
これがエラーの正体だ。

実行例

ルート直下の myapp/ を pytest で読もうとすると、収集時に ModuleNotFoundError で止まる。
python -m pytest か tests/__init__.py を使うと通る。
--import-mode=importlib では tests/__init__.py が効かず、src/ に移した構成は pyproject.toml の pythonpath で通る。

$ pytest -q
==================================== ERRORS ====================================
_____________________ ERROR collecting tests/test_calc.py ______________________
ImportError while importing test module '/tmp/tmp.g9O7vLp6X3/tests/test_calc.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/usr/local/lib/python3.12/importlib/__init__.py:90: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
tests/test_calc.py:1: in <module>
    from myapp.calc import add
E   ModuleNotFoundError: No module named 'myapp'
=========================== short test summary info ============================
ERROR tests/test_calc.py
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
1 error in 0.05s
$ echo $?
2
$ python -m pytest -q
.                                                                        [100%]
1 passed in 0.00s
$ echo $?
0
$ touch tests/__init__.py
$ pytest -q
.                                                                        [100%]
1 passed in 0.00s
$ echo $?
0
$ pytest -q --import-mode=importlib
==================================== ERRORS ====================================
_____________________ ERROR collecting tests/test_calc.py ______________________
ImportError while importing test module '/tmp/tmp.g9O7vLp6X3/tests/test_calc.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
tests/test_calc.py:1: in <module>
    from myapp.calc import add
E   ModuleNotFoundError: No module named 'myapp'
=========================== short test summary info ============================
ERROR tests/test_calc.py
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
1 error in 0.05s
$ echo $?
2
$ mkdir src
$ mv myapp src/
$ python -m pytest -q
==================================== ERRORS ====================================
_____________________ ERROR collecting tests/test_calc.py ______________________
ImportError while importing test module '/tmp/tmp.g9O7vLp6X3/tests/test_calc.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/usr/local/lib/python3.12/importlib/__init__.py:90: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
tests/test_calc.py:1: in <module>
    from myapp.calc import add
E   ModuleNotFoundError: No module named 'myapp'
=========================== short test summary info ============================
ERROR tests/test_calc.py
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
1 error in 0.05s
$ echo $?
2
$ cat pyproject.toml
[tool.pytest.ini_options]
pythonpath = ["src"]
$ pytest -q
.                                                                        [100%]
1 passed in 0.01s
$ echo $?
0
$ pytest -q --import-mode=importlib
.                                                                        [100%]
1 passed in 0.00s
$ echo $?
0

— 2026-10-24 時点の出力

検証環境Python 3.12.15 / Git 2.47.3 / pytest 8.4.2 / 2026-10-24 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.15
  • Git 2.47.3
  • pytest 8.4.2

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. src レイアウトは pythonpath か編集可能インストール

pytest 7.0 以降は、設定ファイルの pythonpath で検索パスを足せる。
パスは rootdir からの相対で、テストセッションの間だけ有効になる。

# pyproject.toml
[tool.pytest.ini_options]
pythonpath = ["src"]

一時的に試すなら PYTHONPATH=src pytest でもよい。
パッケージとして配布する構成なら、pyproject.toml にビルド設定を書いたうえで編集可能インストールにすると、ソースを直してもそのままテストに反映される。

pip install -e .

2. フラットな構成は python -m pytest

python -m pytest は Python の標準の動きとしてカレントディレクトリを sys.path に足すので、ルートの myapp/ が見える。

python -m pytest

毎回 pytest だけで動かしたい場合は、ルートに空の conftest.py を置くか、tests/__init__.py を置く。
前者はルートが、後者は __init__.py が無い最初の上位ディレクトリ(ここではルート)が sys.path に入る。

3. importlib モードではインストールを前提にする

importlib モードでは、手順 2 のうちルートの conftest.py と tests/__init__.py は効かない。
手順 1 の pip install -e . か pythonpath の設定を使う。
python -m pytest は Python 自身がカレントディレクトリを足すので、このモードでも効く。

4. 実行している Python を揃える

python -c "import sys; print(sys.executable)"
python -m pytest

python -m pytest は、いま使っている Python に入った pytest を起動するので、パッケージと pytest の環境が食い違わない。

よくある原因

  1. src レイアウトで src/ が検索パスに無い。
    src/myapp/ に置いたパッケージは、インストールするか検索パスに足さない限り import できない。
  2. フラットな構成で pytest を実行している。
    ルートに myapp/ がある構成でも、pytest コマンドはカレントディレクトリを sys.path に足さない。
  3. --import-mode=importlib にしている。
    公式ドキュメントは新規プロジェクトに importlib モードを勧めているが、このモードでは pytest が sys.path を変更しない。
    conftest.py や __init__.py の位置で検索パスを足してもらう方法が効かなくなる。
  4. 別の Python の pytest を起動している。
    グローバルに入った pytest が先に見つかると、仮想環境に入れたパッケージは見えない。