Asynchronous support

Django has developing support for asynchronous (“async”) Python, but does not yet support asynchronous views or middleware; they will be coming in a future release.

There is limited support for other parts of the async ecosystem; namely, Django can natively talk ASGI, and some async safety support.

Async-safety

Certain key parts of Django are not able to operate safely in an asynchronous environment, as they have global state that is not coroutine-aware. These parts of Django are classified as “async-unsafe”, and are protected from execution in an asynchronous environment. The ORM is the main example, but there are other parts that are also protected in this way.

If you try to run any of these parts from a thread where there is a running event loop, you will get a SynchronousOnlyOperation error. Note that you don’t have to be inside an async function directly to have this error occur. If you have called a synchronous function directly from an asynchronous function without going through something like sync_to_async() or a threadpool, then it can also occur, as your code is still running in an asynchronous context.

If you encounter this error, you should fix your code to not call the offending code from an async context; instead, write your code that talks to async-unsafe in its own, synchronous function, and call that using asgiref.sync.sync_to_async(), or any other preferred way of running synchronous code in its own thread.

If you are absolutely in dire need to run this code from an asynchronous context - for example, it is being forced on you by an external environment, and you are sure there is no chance of it being run concurrently (e.g. you are in a Jupyter notebook), then you can disable the warning with the DJANGO_ALLOW_ASYNC_UNSAFE environment variable.

If you need to do this from within Python, do that with os.environ:

os.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"

Async adapter functions

It is necessary to adapt the calling style when calling synchronous code from an asynchronous context, or vice-versa. For this there are two adapter functions, made available from the asgiref.sync package: async_to_sync() and sync_to_async(). They are used to transition between sync and async calling styles while preserving compatibility.

These adapter functions are widely used in Django. The asgiref package itself is part of the Django project, and it is automatically installed as a dependency when you install Django with pip.

async_to_sync()

async_to_sync(async_function, force_new_loop=False)

Wraps an asynchronous function and returns a synchronous function in its place. Can be used as either a direct wrapper or a decorator:

from asgiref.sync import async_to_sync

sync_function = async_to_sync(async_function)

@async_to_sync
async def async_function(...):
    ...

The asynchronous function is run in the event loop for the current thread, if one is present. If there is no current event loop, a new event loop is spun up specifically for the async function and shut down again once it completes. In either situation, the async function will execute on a different thread to the calling code.

Threadlocals and contextvars values are preserved across the boundary in both directions.

async_to_sync() is essentially a more powerful version of the asyncio.run() function available in Python’s standard library. As well as ensuring threadlocals work, it also enables the thread_sensitive mode of sync_to_async() when that wrapper is used below it.

sync_to_async()

sync_to_async(sync_function, thread_sensitive=False)

Wraps a synchronous function and returns an asynchronous (awaitable) function in its place. Can be used as either a direct wrapper or a decorator:

from asgiref.sync import sync_to_async

async_function = sync_to_async(sync_function)
async_function = sync_to_async(sensitive_sync_function, thread_sensitive=True)

@sync_to_async
def sync_function(...):
    ...

Threadlocals and contextvars values are preserved across the boundary in both directions.

Synchronous functions tend to be written assuming they all run in the main thread, so sync_to_async() has two threading modes:

• thread_sensitive=False (the default): the synchronous function will run in a brand new thread which is then closed once it completes.
• thread_sensitive=True: the synchronous function will run in the same thread as all other thread_sensitive functions, and this will be the main thread, if the main thread is synchronous and you are using the async_to_sync() wrapper.

Thread-sensitive mode is quite special, and does a lot of work to run all functions in the same thread. Note, though, that it relies on usage of async_to_sync() above it in the stack to correctly run things on the main thread. If you use asyncio.run() (or other options instead), it will fall back to just running thread-sensitive functions in a single, shared thread (but not the main thread).

The reason this is needed in Django is that many libraries, specifically database adapters, require that they are accessed in the same thread that they were created in, and a lot of existing Django code assumes it all runs in the same thread (e.g. middleware adding things to a request for later use by a view).

Rather than introduce potential compatibility issues with this code, we instead opted to add this mode so that all existing Django synchronous code runs in the same thread and thus is fully compatible with asynchronous mode. Note, that synchronous code will always be in a different thread to any async code that is calling it, so you should avoid passing raw database handles or other thread-sensitive references around in any new code you write.