Install & Compatibility
Where this runs
tested against v1.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.586s · 31.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.1s · import 0.530s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pytest_asyncio.fixture
✓ import pytest_asyncio
@pytest_asyncio.fixture
async def my_async_fixture():
return await setup_something()
✗ @pytest.fixture
async def my_async_fixture():
return await setup_something() # silently broken in strict mode
Async fixtures must use @pytest_asyncio.fixture, not @pytest.fixture. In strict mode, @pytest.fixture on an async function raises a warning/error. In auto mode it works but is still discouraged.
asyncio mark
✓ @pytest.mark.asyncio
async def test_something():
await asyncio.sleep(0)
✗ async def test_something():
await asyncio.sleep(0) # silently passes without running in strict mode
In strict mode (default since 0.21), async tests must be explicitly marked with @pytest.mark.asyncio or asyncio_mode='auto' must be set globally.
asyncio_mode must be configured. Use @pytest_asyncio.fixture for async fixtures.
# pytest.ini or pyproject.toml — REQUIRED configuration
# [pytest]
# asyncio_mode = auto
# With asyncio_mode=auto, no per-test marks needed:
import pytest_asyncio
@pytest_asyncio.fixture
async def async_client():
client = await create_client()
yield client
await client.close()
async def test_something(async_client):
result = await async_client.fetch()
assert result is not None
# Without asyncio_mode=auto, mark each test explicitly:
import pytest
@pytest.mark.asyncio
async def test_explicit():
await asyncio.sleep(0)
Debug
Known issues
breakingasyncio_mode must be explicitly set. There is no safe default — omitting it causes a DeprecationWarning and the default changed from 'legacy' to 'strict' in 0.21. LLM-generated configs often omit this entirely.fixAdd to pytest.ini: [pytest]\nasyncio_mode = auto\n\nOr use strict mode and mark every test with @pytest.mark.asyncio.
affects: all
breakinglegacy mode removed in 0.23. Any codebase relying on asyncio_mode=legacy (the old default) will fail after upgrading past 0.21.fixMigrate to asyncio_mode=auto (least friction) or asyncio_mode=strict (explicit marks required).
affects: >= 0.23
breakingCustom event_loop fixture redefinition removed in 1.x. A very common pattern in older tutorials — defining a session-scoped event_loop fixture — now raises an error.fixUse the loop_scope argument on @pytest.mark.asyncio or @pytest_asyncio.fixture instead: @pytest_asyncio.fixture(loop_scope='session'). For custom event loop policies, use the event_loop_policy fixture.
affects: >= 1.0
breaking@pytest.asyncio_event_loop mark removed. Was used for class/module-scoped event loops.fixUse @pytest.mark.asyncio(loop_scope='module') or @pytest.mark.asyncio(loop_scope='class') instead.
affects: >= 1.0
gotchaAsync fixtures must use @pytest_asyncio.fixture, not @pytest.fixture. Using @pytest.fixture on an async function works in auto mode but emits warnings and fails in strict mode.fixAlways use @pytest_asyncio.fixture for async fixtures regardless of mode.
affects: all
gotchaasync def test_ functions silently appear to pass without actually running in strict mode if @pytest.mark.asyncio is missing. No error is raised — the test is collected and marked as passed.fixUse asyncio_mode=auto to avoid per-test marks, or ensure every async test has @pytest.mark.asyncio in strict mode.
affects: all
gotchaSeveral versions in the 0.22-0.24 range were yanked from PyPI due to fundamental event loop scoping bugs. Pinning to a yanked version will fail at install time.fixUse 1.x (current stable). If pinning, verify the specific version is not yanked on PyPI.
affects: 0.22.x, some 0.24.x
gotchaTest output contains pip-specific warnings/notices (e.g., about running as root or available updates). These are external to pytest-asyncio's behavior.fixAddress pip warnings according to pip's recommendations, such as using a virtual environment or updating pip, if desired. This output does not indicate a pytest-asyncio specific failure.
affects: all
Errors
Common errors & fixes
RuntimeWarning: coroutine 'test_example' was never awaited
`pytest` attempts to run an `async def` test function as a regular function because `pytest-asyncio` is not installed or correctly configured to manage async tests.
fixInstall `pytest-asyncio` (`pip install pytest-asyncio`). The plugin automatically detects and runs `async def` tests.
RuntimeError: There is no current event loop in thread 'main'
An asynchronous function or coroutine is being called or awaited outside an active `asyncio` event loop managed by `pytest-asyncio`.
fixEnsure all async operations are performed within `async def` test functions or `async` fixtures properly managed by `pytest-asyncio`.
pytest_asyncio.plugin.ScopeMismatch
An `asyncio`-scoped fixture depends on or is configured with a scope incompatible with another `asyncio`-scoped fixture it interacts with.
fixReview the scopes of `pytest_asyncio.fixture` definitions, ensuring dependent fixtures have compatible scopes (e.g., a session-scoped fixture cannot depend on a function-scoped fixture).
DeprecationWarning: The `loop` fixture is deprecated. Use `anyio_backend` or `asyncio_mode` instead.
The test suite or fixtures are explicitly using the `loop` fixture, which has been deprecated in newer `pytest-asyncio` versions in favor of more modern event loop management, often via `anyio`.
fixRemove explicit usage of the `loop` fixture. `pytest-asyncio` typically manages the event loop implicitly for `async def` tests. For explicit backend control, use the `anyio_backend` fixture or configure `asyncio_mode` in `pytest.ini`.
Upgrade
Version history
1.4.0latest on PyPI · released May 26, 2026
Audit
Dependencies
pytest>=8.0requiredpytest-asyncio 1.x requires pytest 8+.