python django async views: Practical Usage and Code Examples

Django's async views let you handle requests without tying up a worker thread, but they change how you interact with the ORM and other sync code. In this article, we'll look at how to write Python Django async views, when they actually help, and where they can hurt.

How Django Executes Views: Sync vs Async

A traditional Django view is a synchronous function: the server calls it, the function runs to completion, and the response is returned. Each request occupies a worker thread for its entire duration. If the view waits on a network call or a database query, that thread is blocked.

An async view is declared with async def instead of def. Django runs it on an event loop, so the view can await other async operations without blocking the loop. This allows a single worker to handle many concurrent requests while they wait on I/O.

The key difference is not speed of execution but concurrency. Async views can interleave work from multiple requests, but they do not make CPU-bound code faster. In fact, CPU-bound code can slow down because of the overhead of the event loop.

Declaring an Async View

Writing an async view is syntactically simple. Use async def and await where needed:

# views.py
import asyncio
from django.http import JsonResponse

async def async_view(request):
    await asyncio.sleep(1)  # Simulate an async I/O operation
    return JsonResponse({"status": "ok"})

This view works like any other Django view when routed. Django detects the async keyword and runs it in an async context. The view can also use async for, async with, and await on any awaitable object.

One important detail: Django's URL resolver and middleware must be compatible. Django automatically adapts sync middleware for async views, but you should be aware that some middleware may still block the event loop if it performs sync I/O.

When Async Views Actually Help

Async views are beneficial when your view spends most of its time waiting on I/O that has an async implementation. Common examples include:

Calling an external HTTP API with an async client like httpx.AsyncClient
Reading from a WebSocket or SSE stream
Performing multiple independent I/O operations concurrently with asyncio.gather
Using an async database driver (e.g., asyncpg via Django's async ORM)

If your view is CPU-bound—like heavy JSON serialization, image processing, or complex calculations—async will not help. It may even hurt because the event loop adds scheduling overhead. In those cases, a sync view running in a thread pool is usually better.

Consider this example where async shines:

import httpx
from django.http import JsonResponse

async def fetch_multiple(urls):
    async with httpx.AsyncClient() as client:
        responses = await asyncio.gather(*(client.get(url) for url in urls))
    return [r.json() for r in responses]

async def aggregate_view(request):
    data = await fetch_multiple(["https://api.example.com/a", "https://api.example.com/b"])
    return JsonResponse(data, safe=False)

Here, the two HTTP requests run concurrently, reducing total latency compared to sequential calls.

The Async ORM and Database Access

Django's ORM has historically been synchronous. Running a query like Model.objects.all() inside an async view blocks the event loop, defeating the purpose of async. To use the ORM safely, you have two options:

Use sync_to_async to run the query in a thread pool.
Use Django's native async ORM support (available since Django 4.1) with an async backend like asyncpg.

sync_to_async is the simplest approach and works with any database backend:

from asgiref.sync import sync_to_async
from myapp.models import MyModel

async def my_async_view(request):
    items = await sync_to_async(MyModel.objects.all)()
    # Or with a queryset: 
    # items = await sync_to_async(list)(MyModel.objects.all())
    return JsonResponse({"count": len(items)})

The first call wraps the queryset's evaluation. The second example shows how to force evaluation of a lazy queryset inside the thread pool.

Django's native async ORM allows you to write async for obj in MyModel.objects.all() directly, but it requires an async database driver and may have limitations with certain query features. Check the Django documentation for your version to see what is supported.

Mixing Sync and Async Code Safely

You will often need to call sync code from an async view. The asgiref.sync module provides two helpers:

sync_to_async(func) converts a sync callable to an async one, running it in a thread pool.
async_to_sync(func) converts an async callable to a sync one, useful for calling async code from sync views or tests.

Be careful with sync_to_async. By default, it uses a thread pool executor. If you call it with a long-running or CPU-bound function, you may exhaust the thread pool. You can set thread_sensitive=True to run in the main thread, but that blocks the event loop. Use thread_sensitive=False for most I/O operations.

from asgiref.sync import sync_to_async

# Run in a thread pool (default)
result = await sync_to_async(some_sync_function, thread_sensitive=False)()

Another pitfall is using blocking libraries like requests directly in an async view. The requests library does not support async, so it blocks the event loop. Use an async HTTP client instead, or wrap requests with sync_to_async if you must.

Performance Tradeoffs and Common Pitfalls

Async views can improve throughput for I/O-bound workloads, but they introduce complexity. Here are the most important tradeoffs:

Event loop blocking: Any sync operation that takes more than a few milliseconds blocks all other requests on that worker. Avoid sync ORM calls, time.sleep, or CPU-heavy loops without wrapping them in sync_to_async.
Thread pool exhaustion: sync_to_async uses a finite thread pool. If many requests call sync code simultaneously, they may queue up, increasing latency.
Middleware compatibility: Django's middleware is sync by default. When a request goes through sync middleware and then an async view, Django may switch between sync and async contexts, adding overhead. Use async middleware if you control it.
Database connection handling: Async views with sync_to_async use the same database connections as sync views, but connection pooling behavior may differ. Ensure your database configuration supports the concurrency level you expect.

A common mistake is assuming async views are always faster. They are not. They are more efficient at handling many concurrent I/O-bound requests, but they can be slower for a single request due to context switching. Measure your actual workload before migrating.

Production Considerations for Async Views

To run async views in production, you need an ASGI server like Uvicorn, Daphne, or Hypercorn. The traditional WSGI server (Gunicorn with sync workers) cannot handle async views. Configure your deployment accordingly.

# Example with Uvicorn
uvicorn myproject.asgi:application --host 0.0.0.0 --port 8000

When scaling, remember that each ASGI worker runs an event loop. The number of concurrent requests is limited by how many tasks the loop can handle, not by thread count. You may need fewer workers than with WSGI, but each worker uses more CPU for the event loop.

Monitor your application for event loop blocking. Tools like asyncio debug mode or custom middleware can log when a task takes too long. Also, be aware that database connections in async contexts may require a connection pool designed for async use, such as asyncpg's pool.

Finally, consider the learning curve for your team. Async views require a different mental model and careful handling of sync code. If your views are mostly simple CRUD operations, sync views are likely sufficient. Reserve async for specific bottlenecks where you can measure a real benefit.