pytest-django-asyncio
pytest-django-asyncio is a small temporary compatibility plugin for projects that need async Django ORM access to
work correctly with pytest-django database fixtures before the equivalent upstream support lands.
It backports the async database fixture behavior proposed
in pytest-django PR #1223 and exposes it as an installed pytest
plugin through pytest11, so downstream projects get the fix automatically after installation.
I'll deprecate it from pypi once the linked MR gets merged into pytest-django.
What does this fix/why do tests fail in async contexts?
pytest-django's normal db fixture wraps each test in a transaction and rolls it back afterwards. In async tests,
Django's async ORM work runs via sync_to_async on a dedicated thread, so the transaction setup and teardown also need
to happen on that thread or database state can escape the rollback boundary.
This package backports the fixture split and async helper approach
from pytest-django PR #1223 so async tests marked with
@pytest.mark.asyncio can use Django DB fixtures safely when this plugin is installed as a normal dependency.
Installation
pip install pytest-django-asyncio
You still need the usual pytest stack in the consuming project:
pytestpytest-djangopytest-asyncioDjango
Supported versions
| Package | Minimum | Tested up to |
|---|---|---|
| Python | 3.10 | 3.14 |
| Django | 4.2 | 6.1 |
| asgiref | 3.9.1 | 3.13 |
| pytest | 8.2 | 9.2 |
| pytest-django | 4.11.1 | 4.14 |
| pytest-asyncio | 1.1.0 | 1.4 |
asgiref 3.13 needs Python 3.11 or newer, and Django 6.x needs Python 3.12 or newer. CI runs the oldest supported combination, recent Django and asgiref pairs, and Django 6.1 on PostgreSQL.
Usage
After installation, pytest auto-loads the plugin through its pytest11 entry point. That means it should
be ready to go as long as you have the package installed in your python environment.
Typical usage:
import pytest
@pytest.mark.asyncio
@pytest.mark.django_db
async def test_async_orm_works():
...
The same backport also works when tests request db or transactional_db directly.
Caveats
- If a project disables pytest plugin auto-loading, it must explicitly add
pytest_django_asyncio.pytest_pluginto its plugin list.
How It Works
The package exposes a thin pytest_plugin.py entry module. During pytest_configure, it applies the small
DjangoDbBlocker.unblock(async_only=...) backport needed by the async path and then registers the real fixture override
module late with @pytest.hookimpl(trylast=True).
That late registration lets this package's _django_db_helper override win over pytest-django.
The sync path delegates back to pytest-django; the async path uses a separate helper modeled
on pytest-django PR #1223: the transaction start/stop run in
the same sync_to_async worker thread that executes the test's ORM calls.
For non-transactional async tests, the main thread and the sync_to_async worker thread share one set of database
connections: the main thread's regular connections, so the test transaction covers ORM calls from either thread. During
the test, connections._connections is replaced by a small stand-in that hands those connections to the two threads,
and Django's inc_thread_sharing() allows their use across threads. Other threads keep their own connections and are
still blocked from database access.
Transactional async tests close the worker thread's connections after each test, so PostgreSQL can drop the test database at the end of the session.
Development
Run the test suite against a specific dependency combination with uv:
uv run --isolated --no-project --python 3.13 --with-editable . \
--with "Django~=6.1.0" --with "asgiref~=3.13.0" pytest
Set POSTGRES_HOST (and optionally POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD) and add
--with "psycopg[binary]" to run against PostgreSQL instead of SQLite. The compat job in
.github/workflows/ci.yml lists the combinations CI runs.
Metadata
Release files for pytest-django-asyncio 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pytest_django_asyncio-0.2.1.tar.gz | 7.0 kB | Without provenance | Details for pytest_django_asyncio-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pytest_django_asyncio-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for pytest_django_asyncio-0.2.1-py3-none-any.whl |
Total release size: 15.7 kB
Release files / pytest_django_asyncio-0.2.1.tar.gz
| Download URL | pytest_django_asyncio-0.2.1.tar.gz |
|---|---|
| Size | 7.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
743b79237b76551273f0c7a92ccd989e09113b8a4b256767319a040a006ff1c8
|
|
BLAKE2b-256 checksum How to use checksums |
2256d56aa2ef88c0e4f7c0f293c8506881f2ec8b6edf25fd2c200d44a2fa01d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / pytest_django_asyncio-0.2.1-py3-none-any.whl
| Download URL | pytest_django_asyncio-0.2.1-py3-none-any.whl |
|---|---|
| Size | 8.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6b91df9c472c5c0e34c953d2ea7039038379e0e74573a6a547a9c7aee5388c33
|
|
BLAKE2b-256 checksum How to use checksums |
c1dd18ed78efc128b652be307fe6beafbcb5c4f7aef45e8f73fa6d808272b5bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for pytest-django-asyncio 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.