できない.dev

pytest「async def functions are not natively supported」の原因と直し方

pytest の async def functions are not natively supported は、async def のテストを動かすプラグインが無いと出る。
pytest-asyncio を入れ、テストに印を付けるか asyncio_mode = auto にすれば直る。

公開: 更新:

症状できない · exit 1
pytest -q
…
=================================== FAILURES ===================================
__________________________________ test_fetch __________________________________
async def functions are not natively supported.
You need to install a suitable plugin for your async framework, for example:
解決後できた · exit 0
pytest -q
.                                                                        [100%]
1 passed in 0.00s

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

要約

pytest 本体は async def のテスト関数を実行できない。
プラグインが無いまま pytest -q を実行すると、pytest 9.1.1 では次の表示でテストが失敗し、終了コード 1 になった。

async def functions are not natively supported.
You need to install a suitable plugin for your async framework, for example:
  - anyio
  - pytest-asyncio
  - pytest-tornasync
  - pytest-trio
  - pytest-twisted
=========================== short test summary info ============================
FAILED test_api.py::test_fetch - Failed: async def functions are not natively...

pytest-asyncio を入れ、テストに @pytest.mark.asyncio を付ければ通る。
pytest 8.4.0 より前は、同じテストが警告付きでスキップされていた。
8.4.0 で失敗として扱うように変わったので、バージョンを上げた途端に CI が落ちることがある。

実行例

python:3.12 の pytest 9.2.0 で async def のテストを実行すると、プラグインが無い状態では失敗した。
pytest-asyncio を入れても印の無いテストは同じエラーで落ち、@pytest.mark.asyncio を付けるか asyncio_mode = auto にすると通った。

$ pytest --version
pytest 9.2.0
$ pytest -q
F                                                                        [100%]
=================================== FAILURES ===================================
__________________________________ test_fetch __________________________________
async def functions are not natively supported.
You need to install a suitable plugin for your async framework, for example:
  - anyio
  - pytest-asyncio
  - pytest-tornasync
  - pytest-trio
  - pytest-twisted
=========================== short test summary info ============================
FAILED test_api.py::test_fetch - Failed: async def functions are not natively...
1 failed in 0.06s
$ echo $?
1
$ pip install pytest-asyncio
$ pytest -q
F                                                                        [100%]
=================================== FAILURES ===================================
__________________________________ test_fetch __________________________________
async def functions are not natively supported.
You need to install a suitable plugin for your async framework, for example:
  - anyio
  - pytest-asyncio
  - pytest-tornasync
  - pytest-trio
  - pytest-twisted
=========================== short test summary info ============================
FAILED test_api.py::test_fetch - Failed: async def functions are not natively...
1 failed in 0.00s
$ echo $?
1
$ cat test_api.py
import asyncio
import pytest
 
@pytest.mark.asyncio
async def test_fetch():
    await asyncio.sleep(0)
    assert True
$ pytest -q
.                                                                        [100%]
1 passed in 0.00s
$ echo $?
0
$ pytest -q
.F                                                                       [100%]
=================================== FAILURES ===================================
______________________________ test_without_mark _______________________________
async def functions are not natively supported.
You need to install a suitable plugin for your async framework, for example:
  - anyio
  - pytest-asyncio
  - pytest-tornasync
  - pytest-trio
  - pytest-twisted
=========================== short test summary info ============================
FAILED test_auto.py::test_without_mark - Failed: async def functions are not ...
1 failed, 1 passed in 0.01s
$ echo $?
1
$ cat pytest.ini
[pytest]
asyncio_mode = auto
$ pytest -q
..                                                                       [100%]
2 passed in 0.00s
$ echo $?
0

— 2026-11-07 時点の出力

検証環境Python 3.12.16 / Git 2.47.3 / pytest 9.2.0 / 2026-11-07 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.16
  • Git 2.47.3
  • pytest 9.2.0

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

解決策

1. pytest-asyncio を入れて印を付ける

pip install pytest-asyncio
import asyncio
import pytest
 
 
@pytest.mark.asyncio
async def test_fetch():
    await asyncio.sleep(0)
    assert True

印を付けたテストは 1 passed になった。

2. 印を省くなら asyncio_mode = auto にする

asyncio だけを使うプロジェクトなら、設定で auto モードにすると、すべての async def のテストに印が付いた扱いになる。

[pytest]
asyncio_mode = auto

pytest.ini に上の 2 行を置くと、印の無いテストも含めて 2 passed になった。
pyproject.toml なら [tool.pytest.ini_options] に asyncio_mode = "auto" を書く。

3. anyio を使っているなら anyio の印を付ける

anyio が入っていれば、pytest-asyncio を入れずに @pytest.mark.anyio で実行できる。

import pytest
 
 
@pytest.fixture
def anyio_backend():
    return "asyncio"
 
 
@pytest.mark.anyio
async def test_any():
    assert True

4. 環境を揃えて起動する

python -m pytest で起動すると、プラグインを入れた仮想環境の pytest が使われる。

async のフィクスチャで出る別のエラー

プラグインが無いまま async def のフィクスチャを同期のテストで使うと、requested an async fixture 'client', with no plugin or hook that handled it で setup がエラーになった。
pytest-asyncio を入れ、テストを async def にして印を付けたうえで、フィクスチャを @pytest_asyncio.fixture で定義すると通った。
auto モードなら @pytest.fixture のままでも通る。

よくある原因

  1. プラグインを入れていない。
    asyncio のコードを試すテストでも、pytest は対応するプラグインが無ければ実行しない。
  2. pytest-asyncio を入れたが、印を付けていない。
    pytest-asyncio 1.4.1 の既定は strict モードで、@pytest.mark.asyncio の付いたテストだけを実行する。
    印の無いテストは、入れる前と同じエラーで失敗した。
  3. pytest を起動している Python が違う。
    グローバルの pytest コマンドが、プラグインを入れた仮想環境の外にあると、入れていないのと同じになる。