04 — Django Async Views: how to write them and when to use them¶
Why this matters¶
Now you have the foundation: you know asyncio, you understand the event loop, and you know what ASGI is. Time to move on to Django itself.
What does an async view look like? How does Django run it? When is it actually useful?
🧠 Mental model¶
A regular sync view is a waiter who takes an order, goes to the kitchen, stands there waiting for the dish to be ready, then returns to the customer. Everything stops.
An async view is a waiter who takes an order, passes it to the kitchen and immediately returns to the dining room. When the dish is ready, they bring it out. Meanwhile, they have served three more customers.
But there is a catch: if the cook (the ORM) still works synchronously, the waiter is still forced to wait. async def is only half the job.
Key terms¶
| Term | What it means |
|---|---|
| Sync view | A regular def function — runs in an OS thread |
| Async view | An async def function — can suspend itself and not block the event loop |
| Middleware | Layers that process the request/response before and after the view |
| Context switch | Switching between the async event loop and a sync OS thread |
| SynchronousOnlyOperation | A Django error raised when sync code runs in an async context |
What an async view looks like¶
Sync view (regular)¶
from django.http import JsonResponse
def my_sync_view(request):
# Runs synchronously in an OS thread
return JsonResponse({"status": "ok", "mode": "sync"})
Async view (minimal)¶
from django.http import JsonResponse
async def my_async_view(request):
# Runs on the event loop (under ASGI)
return JsonResponse({"status": "ok", "mode": "async"})
The only difference is async def. Django automatically detects the view type and runs it accordingly.
How Django runs an async view¶
The result depends on which server you use:
graph TD
A[Request to the URL Router] --> B{Is the view async def?}
B -->|no| C["Run synchronously<br>in an OS thread"]
B -->|yes| D{Which server?}
D -->|WSGI| E["Create a temporary<br>event loop in the thread"]
D -->|ASGI| F{Is there sync middleware?}
F -->|yes| G["Context switch: Async ↔ Sync ↔ Async<br>~1ms penalty each time"]
F -->|no| H["Native execution<br>on the main Event Loop ✅"]
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef decision fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
classDef error fill:#ffebee,stroke:#c62828,stroke-width:3px;
classDef warning fill:#fff8e1,stroke:#e65100,stroke-width:2px;
class A,C step;
class B,D,F decision;
class H success;
class E error;
class G warning;
Pure Async Lifecycle (maximum performance)¶
sequenceDiagram
participant B as Browser
participant ASGI as ASGI Server
participant AM as Async Middleware
participant AV as Async View
B->>ASGI: HTTP Request
ASGI->>AM: Passes the request (Event Loop)
AM->>AV: await view(request)
Note over AV: View awaits the DB or an API<br>(Yields control to the event loop)
AV-->>AM: HttpResponse
AM-->>ASGI: HttpResponse
ASGI-->>B: HTTP Response
The whole path goes through the event loop. No context switches. Maximum efficiency.
Mixed Sync/Async: the switching penalty¶
graph LR
A["ASGI Server<br>Event Loop"] -->|switch| B["Sync Middleware<br>OS Thread"]
B -->|switch| C["Async View<br>async def"]
C -->|switch| D["Sync Middleware<br>Response Phase"]
D -->|switch| E["ASGI Server<br>Response"]
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
classDef error fill:#ffebee,stroke:#c62828,stroke-width:3px;
class A,E step;
class C success;
class B,D error;
Each switch costs about 1 millisecond of penalty. If the middleware is synchronous, Django has to switch back and forth between the event loop and an OS thread on every request.
An async view with a real example: an external API¶
import httpx
from django.http import JsonResponse
async def weather_view(request):
city = request.GET.get("city", "Kyiv")
async with httpx.AsyncClient() as client:
# await: the view is suspended, the event loop serves others
response = await client.get(
f"https://api.example.com/weather?city={city}",
timeout=5.0
)
data = response.json()
return JsonResponse({
"city": city,
"temperature": data["temp"],
"description": data["desc"]
})
While client.get() is waiting for a response from the external server, Django can serve other users. That is exactly the advantage of an async view.
An async view with several parallel requests¶
import asyncio
import httpx
from django.http import JsonResponse
async def dashboard_view(request):
async with httpx.AsyncClient() as client:
# Start three requests at the same time
weather_task = client.get("https://api.example.com/weather")
news_task = client.get("https://api.example.com/news")
stocks_task = client.get("https://api.example.com/stocks")
# Wait for all three — time = time of the slowest request
weather, news, stocks = await asyncio.gather(
weather_task, news_task, stocks_task
)
return JsonResponse({
"weather": weather.json(),
"news": news.json(),
"stocks": stocks.json()
})
Instead of 3 seconds (1+1+1) we get ~1 second — the time of the slowest of the three.
When async views are useful¶
✅ Several external API requests — run in parallel via gather instead of sequentially
✅ Long-lived connections — WebSockets, long polling, Server-Sent Events
✅ High concurrency — thousands of simultaneous requests with low CPU load
✅ Streaming responses — sending large data in chunks
When async views are NOT useful¶
| Situation | Reason |
|---|---|
| WSGI server | The thread is blocked anyway — no benefit |
| Sync middleware in the stack | Context switches wipe out any gain |
| Standard CRUD | ORM + a fast query — a sync view is simpler and sufficient |
| CPU-bound computation | Blocks the event loop — worse than sync |
| Database transactions | transaction.atomic() is not natively supported in async |
Important¶
Don't make a view async just because you can.
An async view adds complexity: you need an ASGI server, async middleware, and async ORM methods. If your view makes one database query and returns a template, a sync view is simpler, clearer and perfectly sufficient.
An async view is justified when there is a real I/O bottleneck: several external API requests, WebSockets, or high concurrency.
A common beginner mistake¶
❌ Sync ORM in an async view¶
from django.http import JsonResponse
from myapp.models import User
async def user_view(request):
# ERROR! A standard ORM call in an async context
user = User.objects.get(id=1) # Will raise SynchronousOnlyOperation!
return JsonResponse({"name": user.username})
✅ Correct — an async ORM method¶
async def user_view(request):
user = await User.objects.aget(id=1) # The asynchronous variant
return JsonResponse({"name": user.username})
More on the async ORM in the next document.
Testing async views¶
Django provides AsyncRequestFactory for testing:
from django.test import AsyncRequestFactory, TestCase
from myapp.views import my_async_view
class MyAsyncViewTest(TestCase):
async def test_async_view(self):
factory = AsyncRequestFactory()
request = factory.get('/async-url/')
# await — because the view is asynchronous
response = await my_async_view(request)
self.assertEqual(response.status_code, 200)
Practical exercise¶
Task 1¶
Create a Django app and write two views:
- sync_view — returns JsonResponse({"type": "sync"})
- async_view — the same, but async def
Run it with uvicorn and check both in a browser or with curl.
Task 2¶
Write async def aggregator_view(request) that runs two await asyncio.sleep(1) calls in parallel via asyncio.gather(). Measure the execution time (you can use time.time()).
Task 3¶
Explain: what happens if sync middleware sits in front of an async view under ASGI? How many context switches happen per request?
Self-check¶
- [ ] I can write an async def view in Django
- [ ] I understand the difference between running an async view under WSGI and under ASGI
- [ ] I know what a context switch is and why it costs ~1ms
- [ ] I understand when an async view is appropriate and when it is not
- [ ] I know that the standard
User.objects.get()cannot be called in an async view
Summary¶
An async view in Django is simply async def instead of def. But to get real benefits you need an ASGI server and async middleware. Under WSGI, an async view runs with no concurrency benefit.
Async views are useful for I/O-bound tasks: several external API requests, WebSockets, streaming. For standard CRUD, a sync view is simpler and perfectly sufficient.
The main trap: sync ORM in an async view will raise SynchronousOnlyOperation. More on that in the next document.