Activities

1 - Django Channels Tutorial

Channels allows you to use WebSockets and other non-HTTP protocols in your Django site. For example you might want to use WebSockets to allow a page on your site to immediately receive updates from your Django server without using HTTP long-polling or other expensive techniques.

In this tutorial we will build a simple chat server, where you can join an online room, post messages to the room, and have others in the same room see those messages immediately.

1. Part 1: Basic Setup
2. Part 2: Implement a Chat Server
3. Part 3: Rewrite Chat Server as Asynchronous
4. Part 4: Automated Testing

How this copy differs from the original

This is a copy of the official Channels tutorial, changed to match the way we have worked in our fork of the MDN Django Tutorial:

• You don’t create a new project. The chat app goes into your existing locallibrary repository, next to catalog. Everywhere the original says mysite, this copy says locallibrary_config.
• Dependencies are managed with uv. pip install becomes uv add, and every command is run with uv run python ….
• Edits to existing files are additions. The original shows complete settings.py and urls.py contents because it assumes a new, empty project. Here you only add lines, so you keep what you built for catalog.
• Part 4’s tests use a separate database file. The original’s test settings would delete your development database; this copy’s don’t.
• Part 4 doesn’t need a manual chromedriver install. Selenium downloads the right driver itself.

This copy was checked on 2026-09-29 with Channels 4.3.2, Daphne 4.2.3, channels-redis 4.3.0, Selenium 4.49, Django 6.1.1, and Python 3.14.

The original tutorial is Copyright (c) Django Software Foundation and individual contributors, and is used under its BSD 3-Clause license.

1.1 - Tutorial Part 1: Basic Setup

In this tutorial we will build a simple chat server. It will have two pages:

• An index view that lets you type the name of a chat room to join.
• A room view that lets you see messages posted in a particular chat room.

The room view will use a WebSocket to communicate with the Django server and listen for any messages that are posted.

We assume that you have completed our fork of the MDN Django Tutorial so far, and that you have your locallibrary repository: a uv project with manage.py, pyproject.toml, and uv.lock at its root, the locallibrary_config project package, and the catalog app. Every command in this tutorial is run from that root folder.

You can check which version of Django your project uses by running the following command in your terminal:

uv run python -m django --version

Installing Channels and Daphne

Add Channels, together with the Daphne server, to your project:

uv add "channels[daphne]"

Just like uv add "django" did when you set up your project, this records the dependency in pyproject.toml, installs it into .venv, and pins the exact versions in uv.lock. Commit both files.

You can check that they’re installed by running the following command:

uv run python -c "import channels; import daphne; print(channels.__version__, daphne.__version__)"

This tutorial was checked with Channels 4.3.2 and Daphne 4.2.3, on Django 6.1 and Python 3.14.

Redis

This tutorial also uses Docker to install and run Redis. We use Redis as the backing store for the channel layer, which is an optional component of the Channels library that we use in the tutorial. Install Docker from its official website - there are official runtimes for Mac OS and Windows that make it easy to use, and packages for many Linux distributions where it can run natively.

Creating the Chat app

You don’t need to create a project: you already have one. We will put the code for the chat server in its own app, alongside catalog.

Make sure you’re in the same directory as manage.py and type this command:

uv run python manage.py startapp chat

That’ll create a directory chat next to catalog, which is laid out like this:

chat/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

For the purposes of this tutorial, we will only be working with chat/views.py and chat/__init__.py. So remove all other files from the chat directory.

After removing unnecessary files, the chat directory should look like:

chat/
    __init__.py
    views.py

We need to tell our project that the chat app is installed. Edit the locallibrary_config/settings.py file and add 'chat' to the end of the INSTALLED_APPS setting, after catalog. Don’t remove anything that’s already there. It’ll look like this:

# locallibrary_config/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Add our new application
    'catalog.apps.CatalogConfig', # This object was created for us in /catalog/apps.py
    'chat',
]

Add the index view

We will now create the first view, an index view that lets you type the name of a chat room to join.

Create a templates directory in your chat directory. Within the templates directory you have just created, create another directory called chat, and within that create a file called index.html to hold the template for the index view.

Your chat directory should now look like:

chat/
    __init__.py
    templates/
        chat/
            index.html
    views.py

Put the following code in chat/templates/chat/index.html:

<!-- chat/templates/chat/index.html -->
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Chat Rooms</title>
    <link rel="icon" href="https://fav.mhciael.com/💬">
</head>

<body>
    <form>
        What chat room would you like to enter?<br>
        <input id="room-name-input" type="text" size="100"><br>
        <button id="room-name-submit" type="submit">Enter</button>
    </form>
    <script>
        document.querySelector('#room-name-input').focus();
        const form = document.querySelector('form');

        form.addEventListener('submit', function (e) {
            e.preventDefault();
            var roomName = document.querySelector('#room-name-input').value;
            window.location.pathname = '/chat/' + roomName + '/';
        });
    </script>
</body>

</html>

Create the view function for the room view. Put the following code in chat/views.py:

# chat/views.py
from django.shortcuts import render


def index(request):
    return render(request, "chat/index.html")

To call the view, we need to map it to a URL - and for this we need a URLconf.

To create a URLconf in the chat directory, create a file called urls.py. Your app directory should now look like:

chat/
    __init__.py
    templates/
        chat/
            index.html
    urls.py
    views.py

In the chat/urls.py file include the following code:

# chat/urls.py
from django.urls import path

from . import views


urlpatterns = [
    path("", views.index, name="chat-index"),
]

The next step is to point the root URLconf at the chat.urls module. Your locallibrary_config/urls.py already imports include() and already includes catalog.urls. Add the chat app in the same style, right after the catalog block:

# locallibrary_config/urls.py
# (after the existing catalog block)
urlpatterns += [
    path('chat/', include('chat.urls')),
]

Leave the admin, catalog, redirect, and static-files entries as they are.

Let’s verify that the index view works. Run the following command:

uv run python manage.py runserver

You’ll see output like the following on the command line:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
September 29, 2026 - 09:28:06
Django version 6.1.1, using settings 'locallibrary_config.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Unlike in the original tutorial, you won’t see a warning about unapplied migrations, because you already ran migrate for catalog.

Go to http://127.0.0.1:8000/chat/ 🔗 in your browser and you should see the text “What chat room would you like to enter?” along with a text input to provide a room name. (The site root still redirects to catalog/, so type the /chat/ path yourself.)

Type in “lobby” as the room name and press enter. You should be redirected to the room view at http://127.0.0.1:8000/chat/lobby/ but we haven’t written the room view yet, so you’ll get a “Page not found” error page.

Go to the terminal where you ran the runserver command and press Control-C to stop the server.

Integrate the Channels library

So far we’ve just created a regular Django app; we haven’t used the Channels library at all. Now it’s time to integrate Channels.

Let’s start by creating a routing configuration for Channels. A Channels routing configuration is an ASGI application that is similar to a Django URLconf, in that it tells Channels what code to run when an HTTP request is received by the Channels server.

Start by replacing the contents of the locallibrary_config/asgi.py file with the following code:

# locallibrary_config/asgi.py
import os

from channels.routing import ProtocolTypeRouter
from django.core.asgi import get_asgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "locallibrary_config.settings")

application = ProtocolTypeRouter(
    {
        "http": get_asgi_application(),
        # Just HTTP for now. (We can add other protocols later.)
    }
)

Now add the Daphne library to the list of installed apps, in order to enable an ASGI version of the runserver command.

Edit the locallibrary_config/settings.py file and add 'daphne' to the top of the INSTALLED_APPS setting. It’ll look like this:

# locallibrary_config/settings.py
INSTALLED_APPS = [
    'daphne',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Add our new application
    'catalog.apps.CatalogConfig', # This object was created for us in /catalog/apps.py
    'chat',
]

You’ll also need to point Daphne at the root routing configuration. Edit the locallibrary_config/settings.py file again and add the following to the bottom of it:

# locallibrary_config/settings.py
# Daphne
ASGI_APPLICATION = "locallibrary_config.asgi.application"

With Daphne now in the installed apps, it will take control of the runserver command, replacing the standard Django development server with the ASGI compatible version.

Let’s ensure that the Channels development server is working correctly. Run the following command:

uv run python manage.py runserver

You’ll see output like the following on the command line:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
September 29, 2026 - 09:28:06
Django version 6.1.1, using settings 'locallibrary_config.settings'
Starting ASGI/Daphne version 4.2.3 development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Notice the line beginning with Starting ASGI/Daphne …. This indicates that the Daphne development server has taken over from the Django development server.

Go to http://127.0.0.1:8000/chat/ 🔗 in your browser and you should still see the index page that we created before. Your catalog pages at http://127.0.0.1:8000/catalog/ 🔗 still work too: Daphne serves them the same way.

Go to the terminal where you ran the runserver command and press Control-C to stop the server.

This tutorial continues in Tutorial 2.

1.2 - Tutorial Part 2: Implement a Chat Server

This tutorial begins where Tutorial 1 left off. We’ll get the room page working so that you can chat with yourself and others in the same room.

Add the room view

We will now create the second view, a room view that lets you see messages posted in a particular chat room.

Create a new file chat/templates/chat/room.html. Your app directory should now look like:

chat/
    __init__.py
    templates/
        chat/
            index.html
            room.html
    urls.py
    views.py

Create the view template for the room view in chat/templates/chat/room.html:

<!-- chat/templates/chat/room.html -->
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Chat Room</title>
    <link rel="icon" href="https://fav.mhciael.com/💬">
</head>

<body>
    <form>
        <textarea id="chat-log" cols="100" rows="20"></textarea><br>
        <input id="chat-message-input" type="text" size="100"><br>
        <button id="chat-message-submit" type="submit" value="Send">Send</button>
        {{ room_name|json_script:"room-name" }}
    </form>
    <script>
        const roomName = JSON.parse(document.getElementById('room-name').textContent);

        // Use wss:// when the page was loaded over https://, otherwise ws://
        const wsScheme = window.location.protocol === 'https:' ? 'wss://' : 'ws://';

        const chatSocket = new WebSocket(
            wsScheme
            + window.location.host
            + '/ws/chat/'
            + roomName
            + '/'
        );

        chatSocket.onmessage = function (e) {
            const data = JSON.parse(e.data);
            document.querySelector('#chat-log').value += (data.message + '\n');
        };

        chatSocket.onclose = function (e) {
            console.error('Chat socket closed unexpectedly');
        };

        document.querySelector('#chat-message-input').focus();


        document.querySelector('form').addEventListener('submit', (e) => {
            e.preventDefault();
            const messageInputDom = document.querySelector('#chat-message-input');
            const message = messageInputDom.value;
            chatSocket.send(JSON.stringify({
                'message': message
            }));
            messageInputDom.value = '';
        });
    </script>
</body>

</html>

Create the view function for the room view in chat/views.py:

# chat/views.py
from django.shortcuts import render


def index(request):
    return render(request, "chat/index.html")


def room(request, room_name):
    return render(request, "chat/room.html", {"room_name": room_name})

Create the route for the room view in chat/urls.py:

# chat/urls.py
from django.urls import path

from . import views

urlpatterns = [
    path("", views.index, name="chat-index"),
    path("<str:room_name>/", views.room, name="chat-room"),
]

Start the Channels development server:

uv run python manage.py runserver

Go to http://127.0.0.1:8000/chat/ 🔗 in your browser to see the index page.

Type in “lobby” as the room name and press enter. You should be redirected to the room page at http://127.0.0.1:8000/chat/lobby 🔗 which now displays an empty chat log.

Type the message “hello” and press enter. Nothing happens. In particular the message does not appear in the chat log. Why?

The room view is trying to open a WebSocket to the URL ws://127.0.0.1:8000/ws/chat/lobby/ but we haven’t created a consumer that accepts WebSocket connections yet. If you open your browser’s JavaScript console, you should see an error that looks like:

WebSocket connection to 'ws://127.0.0.1:8000/ws/chat/lobby/' failed: Unexpected response code: 500

Write your first consumer

When Django accepts an HTTP request, it consults the root URLconf to lookup a view function, and then calls the view function to handle the request. Similarly, when Channels accepts a WebSocket connection, it consults the root routing configuration to lookup a consumer, and then calls various functions on the consumer to handle events from the connection.

We will write a basic consumer that accepts WebSocket connections on the path /ws/chat/ROOM_NAME/ that takes any message it receives on the WebSocket and echos it back to the same WebSocket.

Create a new file chat/consumers.py. Your app directory should now look like:

chat/
    __init__.py
    consumers.py
    templates/
        chat/
            index.html
            room.html
    urls.py
    views.py

Put the following code in chat/consumers.py:

# chat/consumers.py
import json

from channels.generic.websocket import WebsocketConsumer


class ChatConsumer(WebsocketConsumer):
    def connect(self):
        self.accept()

    def disconnect(self, close_code):
        pass

    def receive(self, text_data):
        text_data_json = json.loads(text_data)
        message = text_data_json["message"]

        self.send(text_data=json.dumps({"message": message}))

This is a synchronous WebSocket consumer that accepts all connections, receives messages from its client, and echos those messages back to the same client. For now it does not broadcast messages to other clients in the same room.

We need to create a routing configuration for the chat app that has a route to the consumer. Create a new file chat/routing.py. Your app directory should now look like:

chat/
    __init__.py
    consumers.py
    routing.py
    templates/
        chat/
            index.html
            room.html
    urls.py
    views.py

Put the following code in chat/routing.py:

# chat/routing.py
from django.urls import re_path

from . import consumers

websocket_urlpatterns = [
    re_path(r"ws/chat/(?P<room_name>\w+)/$", consumers.ChatConsumer.as_asgi()),
]

We call the as_asgi() classmethod in order to get an ASGI application that will instantiate an instance of our consumer for each user-connection. This is similar to Django’s as_view(), which plays the same role for per-request Django view instances.

(Note we use re_path() due to limitations in URLRouter.)

The next step is to point the main ASGI configuration at the chat.routing module. Replace the contents of locallibrary_config/asgi.py with the code below. The highlighted lines are what changed since you edited this file in Part 1:

• Imports: AuthMiddlewareStack and AllowedHostsOriginValidator are new, and URLRouter joins ProtocolTypeRouter on the existing channels.routing line.
• django_asgi_app: get_asgi_application() is now called before chat.routing is imported, and its result is saved in django_asgi_app. The comment above it explains why the order matters.
• from chat.routing import websocket_urlpatterns: this import is new. It deliberately sits below the get_asgi_application() call rather than at the top of the file with the other imports.
• "http": now uses the saved django_asgi_app instead of calling get_asgi_application() again.
• "websocket": this key is new and replaces the # Just HTTP for now comment.

# locallibrary_config/asgi.py
import os

from channels.auth import AuthMiddlewareStack
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.security.websocket import AllowedHostsOriginValidator
from django.core.asgi import get_asgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "locallibrary_config.settings")
# Initialize Django ASGI application early to ensure the AppRegistry
# is populated before importing code that may import ORM models.
django_asgi_app = get_asgi_application()

from chat.routing import websocket_urlpatterns

application = ProtocolTypeRouter(
    {
        "http": django_asgi_app,
        "websocket": AllowedHostsOriginValidator(
            AuthMiddlewareStack(URLRouter(websocket_urlpatterns))
        ),
    }
)

This root routing configuration specifies that when a connection is made to the Channels development server, the ProtocolTypeRouter will first inspect the type of connection. If it is a WebSocket connection (ws:// or wss://), the connection will be given to the AuthMiddlewareStack.

The AuthMiddlewareStack will populate the connection’s scope with a reference to the currently authenticated user, similar to how Django’s AuthenticationMiddleware populates the request object of a view function with the currently authenticated user. (Scopes will be discussed later in this tutorial.) Then the connection will be given to the URLRouter.

The URLRouter will examine the HTTP path of the connection to route it to a particular consumer, based on the provided url patterns.

Let’s verify that the consumer for the /ws/chat/ROOM_NAME/ path works. Django’s session framework needs the database, which you already migrated while building catalog. Run migrate anyway to be sure, and then start the Channels development server:

uv run python manage.py migrate

You should see:

Operations to perform:
  Apply all migrations: admin, auth, catalog, contenttypes, sessions
Running migrations:
  No migrations to apply.

Then start the server:

uv run python manage.py runserver

Go to the room page at http://127.0.0.1:8000/chat/lobby 🔗 which now displays an empty chat log.

Type the message “hello” and press enter. You should now see “hello” echoed in the chat log.

However if you open a second browser tab to the same room page at http://127.0.0.1:8000/chat/lobby 🔗 and type in a message, the message will not appear in the first tab. For that to work, we need to have multiple instances of the same ChatConsumer be able to talk to each other. Channels provides a channel layer abstraction that enables this kind of communication between consumers.

Go to the terminal where you ran the runserver command and press Control-C to stop the server.

Enable a channel layer

A channel layer is a kind of communication system. It allows multiple consumer instances to talk with each other, and with other parts of Django.

A channel layer provides the following abstractions:

• A channel is a mailbox where messages can be sent to. Each channel has a name. Anyone who has the name of a channel can send a message to the channel.

• A group is a group of related channels. A group has a name. Anyone who has the name of a group can add/remove a channel to the group by name and send a message to all channels in the group. It is not possible to enumerate what channels are in a particular group.

Every consumer instance has an automatically generated unique channel name, and so can be communicated with via a channel layer.

In our chat application we want to have multiple instances of ChatConsumer in the same room communicate with each other. To do that we will have each ChatConsumer add its channel to a group whose name is based on the room name. That will allow ChatConsumers to transmit messages to all other ChatConsumers in the same room.

We will use a channel layer that uses Redis as its backing store. To start a Redis server on port 6379, run the following command in a separate terminal (press Control-C to stop it):

docker run --rm -p 6379:6379 redis:7

We need to install channels_redis so that Channels knows how to interface with Redis. Run the following command:

uv add channels-redis

Commit the updated pyproject.toml and uv.lock again.

Before we can use a channel layer, we must configure it. Where Redis lives is configuration that differs between machines (your laptop vs. a deployed server), so it belongs in your env file rather than hard-coded in settings.py. You set up .env, .env.example, and django-environ back in Prep 02.

At that point your env file only held the DJANGO_SUPERUSER_* values, so now you’ll add two new variables: REDIS_URL, which tells Django how to reach the Redis server you just started, and REDIS_SOCKET_TIMEOUT, which sets how many seconds to wait on Redis before giving up.

A Redis URL has the form redis://HOST:PORT/DB:

• redis:// is the scheme (use rediss://, with two s’s, for a TLS connection to a hosted Redis)
• HOST is the machine Redis runs on. Your Docker container (or redis-server) is on your own machine, so use 127.0.0.1
• PORT is the port Redis listens on. The -p 6379:6379 in the docker run command above publishes Redis on port 6379
• DB is the Redis database number. A fresh Redis server has databases 0–15; we’ll use 0

1. Open .env (in the root of your project, next to manage.py) and add these lines below the existing DJANGO_SUPERUSER_* lines:

   DJANGO_SUPERUSER_USERNAME="me"
   DJANGO_SUPERUSER_PASSWORD="me"
   DJANGO_SUPERUSER_EMAIL="me@me.me"
   REDIS_URL="redis://127.0.0.1:6379/0"
   REDIS_SOCKET_TIMEOUT=10
   

2. Add the same REDIS_URL and REDIS_SOCKET_TIMEOUT lines to .env.example, so anyone who copies it to create their own .env gets a working value.

3. Commit .env.example (but never .env; it should already be listed in your .gitignore).

If you ran Redis on a different port (e.g. docker run --rm -p 6380:6379 redis:7 because something else was using 6379), change only the port in your .env, for example REDIS_URL="redis://127.0.0.1:6380/0". Your settings.py won’t need to change. Likewise, if you still see Redis timeouts, try raising REDIS_SOCKET_TIMEOUT in your .env.

Next, edit the locallibrary_config/settings.py file and add a CHANNEL_LAYERS setting to the bottom, below the ASGI_APPLICATION line you added in Part 1. Instead of hard-coding the host and port, read the URL and timeout from your env file with the env object defined near the top of settings.py. It should look like:

# locallibrary_config/settings.py
# Channels
ASGI_APPLICATION = "locallibrary_config.asgi.application"
CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {
            "hosts": [
                {
                    "address": env("REDIS_URL"),
                    "socket_timeout": env.int("REDIS_SOCKET_TIMEOUT"),
                }
            ],
        },
    },
}

Let’s make sure that the channel layer can communicate with Redis. Open a Django shell and run the following commands:

uv run python manage.py shell

import channels.layers
channel_layer = channels.layers.get_channel_layer()
from asgiref.sync import async_to_sync
async_to_sync(channel_layer.send)('test_channel', {'type': 'hello'})
async_to_sync(channel_layer.receive)('test_channel')

You should see:

{'type': 'hello'}

(The number of objects the shell imports automatically depends on your models; that’s the same auto-import you’ve seen in the shell before.)

Type Control-D (or exit()) to exit the Django shell.

Now that we have a channel layer, let’s use it in ChatConsumer. Put the following code in chat/consumers.py, replacing the old code:

# chat/consumers.py
import json

from asgiref.sync import async_to_sync
from channels.generic.websocket import WebsocketConsumer


class ChatConsumer(WebsocketConsumer):
    def connect(self):
        self.room_name = self.scope["url_route"]["kwargs"]["room_name"]
        self.room_group_name = f"chat_{self.room_name}"

        # Join room group
        async_to_sync(self.channel_layer.group_add)(
            self.room_group_name, self.channel_name
        )

        self.accept()

    def disconnect(self, close_code):
        # Leave room group
        async_to_sync(self.channel_layer.group_discard)(
            self.room_group_name, self.channel_name
        )

    # Receive message from WebSocket
    def receive(self, text_data):
        text_data_json = json.loads(text_data)
        message = text_data_json["message"]

        # Send message to room group
        async_to_sync(self.channel_layer.group_send)(
            self.room_group_name, {"type": "chat.message", "message": message}
        )

    # Receive message from room group
    def chat_message(self, event):
        message = event["message"]

        # Send message to WebSocket
        self.send(text_data=json.dumps({"message": message}))

When a user posts a message, a JavaScript function will transmit the message over WebSocket to a ChatConsumer. The ChatConsumer will receive that message and forward it to the group corresponding to the room name. Every ChatConsumer in the same group (and thus in the same room) will then receive the message from the group and forward it over WebSocket back to JavaScript, where it will be appended to the chat log.

Several parts of the new ChatConsumer code deserve further explanation:

• self.scope["url_route"]["kwargs"]["room_name"]

  • Obtains the 'room_name' parameter from the URL route in chat/routing.py that opened the WebSocket connection to the consumer.
  • Every consumer has a scope that contains information about its connection, including in particular any positional or keyword arguments from the URL route and the currently authenticated user if any.

• self.room_group_name = f"chat_{self.room_name}"

  • Constructs a Channels group name directly from the user-specified room name, without any quoting or escaping.
  • Group names may only contain alphanumerics, hyphens, underscores, or periods. Therefore this example code will fail on room names that have other characters.

• async_to_sync(self.channel_layer.group_add)(...)

  • Joins a group.
  • The async_to_sync(...) wrapper is required because ChatConsumer is a synchronous WebsocketConsumer but it is calling an asynchronous channel layer method. (All channel layer methods are asynchronous.)
  • Group names are restricted to ASCII alphanumerics, hyphens, and periods only and are limited to a maximum length of 100 in the default backend. Since this code constructs a group name directly from the room name, it will fail if the room name contains any characters that aren’t valid in a group name or exceeds the length limit.

• self.accept()

  • Accepts the WebSocket connection.
  • If you do not call accept() within the connect() method then the connection will be rejected and closed. You might want to reject a connection for example because the requesting user is not authorized to perform the requested action.
  • It is recommended that accept() be called as the last action in connect() if you choose to accept the connection.

• async_to_sync(self.channel_layer.group_discard)(...)

  • Leaves a group.

• async_to_sync(self.channel_layer.group_send)

  • Sends an event to a group.
  • An event has a special 'type' key corresponding to the name of the method that should be invoked on consumers that receive the event. This translation is done by replacing . with _, thus in this example, chat.message calls the chat_message method.

Let’s verify that the new consumer for the /ws/chat/ROOM_NAME/ path works. To start the Channels development server, run the following command:

uv run python manage.py runserver

Open a browser tab to the room page at http://127.0.0.1:8000/chat/lobby/. Open a second browser tab to the same room page.

In the second browser tab, type the message “hello” and press enter. You should now see “hello” echoed in the chat log in both the second browser tab and in the first browser tab.

You now have a basic fully-functional chat server!

This tutorial continues in Tutorial 3.

1.3 - Tutorial Part 3: Rewrite Chat Server as Asynchronous

This tutorial begins where Tutorial 2 left off. We’ll rewrite the consumer code to be asynchronous rather than synchronous to improve its performance.

Rewrite the consumer to be asynchronous

The ChatConsumer that we have written is currently synchronous. Synchronous consumers are convenient because they can call regular synchronous I/O functions such as those that access Django models without writing special code. However asynchronous consumers can provide a higher level of performance since they don’t need to create additional threads when handling requests.

ChatConsumer only uses async-native libraries (Channels and the channel layer) and in particular it does not access synchronous code. Therefore it can be rewritten to be asynchronous without complications.

Let’s rewrite ChatConsumer to be asynchronous. Put the following code in chat/consumers.py:

# chat/consumers.py
import json

from channels.generic.websocket import AsyncWebsocketConsumer


class ChatConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        self.room_name = self.scope["url_route"]["kwargs"]["room_name"]
        self.room_group_name = f"chat_{self.room_name}"

        # Join room group
        await self.channel_layer.group_add(self.room_group_name, self.channel_name)

        await self.accept()

    async def disconnect(self, close_code):
        # Leave room group
        await self.channel_layer.group_discard(self.room_group_name, self.channel_name)

    # Receive message from WebSocket
    async def receive(self, text_data):
        text_data_json = json.loads(text_data)
        message = text_data_json["message"]

        # Send message to room group
        await self.channel_layer.group_send(
            self.room_group_name, {"type": "chat.message", "message": message}
        )

    # Receive message from room group
    async def chat_message(self, event):
        message = event["message"]

        # Send message to WebSocket
        await self.send(text_data=json.dumps({"message": message}))

This new code for ChatConsumer is very similar to the original code, with the following differences:

• ChatConsumer now inherits from AsyncWebsocketConsumer rather than WebsocketConsumer.
• All methods are async def rather than just def.
• await is used to call asynchronous functions that perform I/O.
• async_to_sync is no longer needed when calling methods on the channel layer.

Let’s verify that the consumer for the /ws/chat/ROOM_NAME/ path still works. Make sure Redis is still running, then start the Channels development server:

uv run python manage.py runserver

Open a browser tab to the room page at http://127.0.0.1:8000/chat/lobby/. Open a second browser tab to the same room page.

In the second browser tab, type the message “hello” and press enter. You should now see “hello” echoed in the chat log in both the second browser tab and in the first browser tab.

Now your chat server is fully asynchronous!

This tutorial continues in Tutorial 4.

1.4 - Tutorial Part 4: Automated Testing

This tutorial begins where Tutorial 3 left off. We’ve built a simple chat server and now we’ll create some automated tests for it.

Testing the views

To ensure that the chat server keeps working, we will write some tests.

We will write a suite of end-to-end tests using Selenium to control a Chrome web browser. These tests will ensure that:

• when a chat message is posted then it is seen by everyone in the same room
• when a chat message is posted then it is not seen by anyone in a different room

Install the Chrome web browser, if you do not already have it.

Install Selenium as a development dependency, like the testing tools in the MDN tutorial, so that it is never installed on your production server. Run the following command:

uv add --dev selenium

Commit the updated pyproject.toml and uv.lock.

You don’t need to install chromedriver yourself. The first time the tests start Chrome, Selenium finds a matching chromedriver or downloads one automatically.

Create a new file chat/tests.py. Your app directory should now look like:

chat/
    __init__.py
    consumers.py
    routing.py
    templates/
        chat/
            index.html
            room.html
    tests.py
    urls.py
    views.py

Put the following code in chat/tests.py:

# chat/tests.py
from channels.testing import ChannelsLiveServerTestCase
from selenium import webdriver
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.by import By
from selenium.webdriver.common.keys import Keys
from selenium.webdriver.support.wait import WebDriverWait


class ChatTests(ChannelsLiveServerTestCase):
    serve_static = True  # emulate StaticLiveServerTestCase

    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        try:
            # NOTE: Selenium finds or downloads a matching chromedriver automatically
            cls.driver = webdriver.Chrome()
        except:
            super().tearDownClass()
            raise

    @classmethod
    def tearDownClass(cls):
        cls.driver.quit()
        super().tearDownClass()

    def test_when_chat_message_posted_then_seen_by_everyone_in_same_room(self):
        try:
            self._enter_chat_room("room_1")

            self._open_new_window()
            self._enter_chat_room("room_1")

            self._switch_to_window(0)
            self._post_message("hello")
            WebDriverWait(self.driver, 2).until(
                lambda _: "hello" in self._chat_log_value,
                "Message was not received by window 1 from window 1",
            )
            self._switch_to_window(1)
            WebDriverWait(self.driver, 2).until(
                lambda _: "hello" in self._chat_log_value,
                "Message was not received by window 2 from window 1",
            )
        finally:
            self._close_all_new_windows()

    def test_when_chat_message_posted_then_not_seen_by_anyone_in_different_room(self):
        try:
            self._enter_chat_room("room_1")

            self._open_new_window()
            self._enter_chat_room("room_2")

            self._switch_to_window(0)
            self._post_message("hello")
            WebDriverWait(self.driver, 2).until(
                lambda _: "hello" in self._chat_log_value,
                "Message was not received by window 1 from window 1",
            )

            self._switch_to_window(1)
            self._post_message("world")
            WebDriverWait(self.driver, 2).until(
                lambda _: "world" in self._chat_log_value,
                "Message was not received by window 2 from window 2",
            )
            self.assertTrue(
                "hello" not in self._chat_log_value,
                "Message was improperly received by window 2 from window 1",
            )
        finally:
            self._close_all_new_windows()

    # === Utility ===

    def _enter_chat_room(self, room_name):
        self.driver.get(self.live_server_url + "/chat/")
        ActionChains(self.driver).send_keys(room_name, Keys.ENTER).perform()
        WebDriverWait(self.driver, 2).until(
            lambda _: room_name in self.driver.current_url
        )

    def _open_new_window(self):
        self.driver.execute_script('window.open("about:blank", "_blank");')
        self._switch_to_window(-1)

    def _close_all_new_windows(self):
        while len(self.driver.window_handles) > 1:
            self._switch_to_window(-1)
            self.driver.execute_script("window.close();")
        if len(self.driver.window_handles) == 1:
            self._switch_to_window(0)

    def _switch_to_window(self, window_index):
        self.driver.switch_to.window(self.driver.window_handles[window_index])

    def _post_message(self, message):
        ActionChains(self.driver).send_keys(message, Keys.ENTER).perform()

    @property
    def _chat_log_value(self):
        return self.driver.find_element(
            by=By.CSS_SELECTOR, value="#chat-log"
        ).get_property("value")

Our test suite extends ChannelsLiveServerTestCase rather than Django’s usual suites for end-to-end tests (StaticLiveServerTestCase or LiveServerTestCase) so that URLs inside the Channels routing configuration like /ws/chat/ROOM_NAME/ will work inside the suite.

We are using sqlite3, which for testing is run as an in-memory database, and therefore the tests will not run correctly. We need to tell our project that the test database should be a file instead. Edit the DATABASES setting in locallibrary_config/settings.py and add a TEST entry, keeping the ENGINE and NAME lines you already have:

# locallibrary_config/settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
        'TEST': {
            'NAME': BASE_DIR / 'test_db.sqlite3',
        },
    }
}

Django creates test_db.sqlite3 while the tests run, and it should never be committed. If you started your .gitignore from GitHub’s Python template, its *.sqlite3 line already ignores it. Otherwise, add this line:

test_db.sqlite3

The tests use your real channel layer, so Redis must be running (see Part 2). To run the tests, run the following command:

uv run python manage.py test chat.tests

You should see output that looks like:

Creating test database for alias 'default'...
Found 2 test(s).
System check identified no issues (0 silenced).
Not Found: /favicon.ico
..
----------------------------------------------------------------------
Ran 2 tests in 8.953s

OK
Destroying test database for alias 'default'...

Chrome windows will open and close by themselves while the tests run. The Not Found: /favicon.ico line is Chrome asking for an icon the chat pages don’t have; you can ignore it.

You now have a tested chat server!

What’s next?

Congratulations! You’ve fully implemented a chat server, made it performant by writing it in asynchronous style, and written automated tests to ensure it won’t break.

This is the end of the tutorial. At this point you should know enough to start an app of your own that uses Channels and start fooling around. As you need to learn new tricks, come back to the rest of the Channels documentation.

2 - Django Ninja Quickstart

In three short pages you’ll build a small chat API for the chat rooms in your locallibrary: people can browse rooms, filter and paginate them, read a room’s messages, sign in, and post a message that shows up live in the chat page. Along the way you’ll see most of what makes Django Ninja pleasant to use: type hints that validate input, schemas generated from your models, interactive docs, auth, and routers.

This guide assumes you already know Django: projects, apps, models and migrations. It won’t explain those; it only shows the Django Ninja parts.

Before you start

We assume that you have completed preps 01-06 (our fork of the MDN Django Tutorial through Part 8) and all four parts of our Channels tutorial. You have your locallibrary repository: a uv project with manage.py, pyproject.toml, and uv.lock at its root, the locallibrary_config project package, the catalog app, and the asynchronous chat app. Every command in this guide is run from that root folder.

The chat app works, but it forgets everything: a message exists only while it travels through Redis to the browsers in the room. An API that lists rooms and messages needs them in the database. So before the Django Ninja parts, page 2 adds Room and Message models to the chat app, saves every message to the database, and shows a room’s history when you open it.

How this copy differs from the original

This is a copy of the official Django Ninja Quick Start, changed to match the way we have worked in our fork of the MDN Django Tutorial and our Channels tutorial:

• You don’t create a new project or app. The API goes into your existing locallibrary repository. Everywhere the original says mysite, this copy says locallibrary_config, and the original’s events app is your chat app.
• Chat rooms instead of events. The original builds an API for an Event model, and users register for events. This copy builds the same API for a Room model, and users post Messages to rooms. Each piece of the original has a counterpart here: EventFilter’s upcoming filter becomes RoomFilter’s recent filter, the 409 for an event that clashes with another becomes a 409 for a room name that’s taken, and the nested RegistrationOut schema becomes a nested MessageOut schema.
• You add models to the chat app first. Page 2 starts with Room and Message models, saves messages from the WebSocket consumer, and shows a room’s saved messages when you open it. The original has nothing like this, because it starts from an empty app.
• Posted messages go to the chat page. On page 3, a message posted through the API is also sent to everyone in the room over the channel layer, so it appears in the chat page right away.
• Dependencies are managed with uv. pip install becomes uv add, and every command is run with uv run python ….
• Edits to existing files are additions. The original shows complete urls.py contents because it assumes a new, empty project. Here you only add lines, so you keep what you built for catalog and chat.

This copy follows the Django Ninja documentation as of 2026-10-19 (Django Ninja 1.7.1), on Django 6.1, Channels 4.3, and Python 3.14. Once you finish, continue with our Django Ninja Tutorial.

The original Quick Start is Copyright (c) 2025 Vitaliy Kucheryaviy, and is used under its MIT license.

2.1 - Quick Start Part 1: First API

Install

Add Django Ninja to your project:

uv add django-ninja

Just like uv add "channels[daphne]" did in the Channels tutorial, this records the dependency in pyproject.toml, installs it into .venv, and pins the exact versions in uv.lock. Commit both files.

Django Ninja works with any Django project. The original Quick Start creates a new project and an events app at this point. You don’t: you already have a project, locallibrary_config, and the chat app plays the part of events for the rest of this guide.

Django Ninja itself doesn’t need to be in INSTALLED_APPS, but adding "ninja" lets Django’s runserver and collectstatic serve the interactive docs’ assets locally instead of from a CDN. Edit locallibrary_config/settings.py and add 'ninja' to the end of INSTALLED_APPS, after chat. Don’t remove anything that’s already there:

# locallibrary_config/settings.py
INSTALLED_APPS = [
    'daphne',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Add our new application
    'catalog.apps.CatalogConfig', # This object was created for us in /catalog/apps.py
    'chat',
    'ninja',
]

Create the API

An API starts with a NinjaAPI instance. Create locallibrary_config/api.py next to urls.py:

# locallibrary_config/api.py
from ninja import NinjaAPI

api = NinjaAPI()


@api.get("/hello")
def hello(request, name: str = "world"):
    return {"message": f"Hello, {name}!"}

Then mount it in locallibrary_config/urls.py, like any other set of views. That file already includes catalog.urls and chat.urls. Add the API in the same style, at the end of the file:

# locallibrary_config/urls.py
# (after the existing blocks)
# Mount the Django Ninja API
from .api import api

urlpatterns += [
    path('api/', api.urls),
]

Leave the admin, catalog, chat, redirect, and static-files entries as they are.

Run the server:

uv run python manage.py runserver

This is the Daphne development server from the Channels tutorial. It serves your Django Ninja API the same way it serves your catalog pages. Redis doesn’t need to be running for this page; only the chat’s WebSockets use it.

Open http://127.0.0.1:8000/api/hello?name=Ninja 🔗:

{"message": "Hello, Ninja!"}

A few things happened with no extra code:

• @api.get("/hello") registered a GET endpoint at /api/hello.
• The request argument is a regular Django HttpRequest, so request.user, sessions and middleware all work as usual.
• name: str = "world" became an optional query parameter with a default value.
• The returned dict was serialized to JSON.

Type hints are validation

Every argument’s type hint says what the endpoint accepts. Add an endpoint with two required integers to locallibrary_config/api.py:

# locallibrary_config/api.py
@api.get("/add")
def add(request, a: int, b: int):
    return {"result": a + b}

/api/add?a=2&b=3 🔗 returns {"result": 5}, and a and b arrive in your function as real ints, not strings. Invalid input never reaches your code. Try /api/add?a=2&b=three 🔗:

{
    "detail": [
        {
            "type": "int_parsing",
            "loc": ["query", "b"],
            "msg": "Input should be a valid integer, unable to parse string as an integer"
        }
    ]
}

The response has status code 422, and the error points to exactly which parameter failed and why. The same works for float, bool, date, datetime, UUID, enums, and more. See Query Parameters for the full list.

Interactive docs

Now open http://127.0.0.1:8000/api/docs 🔗:

Django Ninja generates an OpenAPI schema from your code, including parameter types, required fields and responses, and serves it with Swagger UI. Click an endpoint, then Try it out to call it from the browser. The raw schema is at /api/openapi.json, ready for client generators and API tools.

The docs are never out of date, because they are built from the same type hints that validate your requests. See OpenAPI & Interactive Docs to customize them.

Next

So far the API only returns hand-built dicts. Next, give your chat rooms and messages a home in the database, connect the API to them, and build a real CRUD API: Models & Schemas.

2.2 - Quick Start Part 2: Models & Schemas

On this page you’ll give your chat rooms and messages a home in the database, then turn the Room model into a complete CRUD API, and add pagination and filtering. Along the way you’ll see how schemas are generated from your models.

The models

Nothing Ninja-specific here, just regular Django models. The original Quick Start has a single Event model. Your chat needs two: a Room, and the Messages posted in it.

In Part 1 of the Channels tutorial, you deleted chat/models.py because the chat didn’t store anything. Create it again, with this code:

# chat/models.py
from django.conf import settings
from django.db import models


class Room(models.Model):
    name = models.CharField(max_length=50, unique=True)
    topic = models.CharField(max_length=200, blank=True, default="")
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name


class Message(models.Model):
    room = models.ForeignKey(Room, related_name="messages", on_delete=models.CASCADE)
    author = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        null=True,
        blank=True,
        related_name="chat_messages",
        on_delete=models.SET_NULL,
    )
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ["created_at", "id"]

    def __str__(self):
        return f"{self.author or 'anonymous'} in {self.room}: {self.content[:50]}"

• A room’s name is the name in its URL, like lobby in /chat/lobby/, so two rooms can’t share one: unique=True. It’s also part of the room’s Channels group name (chat_lobby), and group names must be shorter than 100 characters, so 50 leaves plenty of room.
• topic is optional. blank=True lets forms and the admin leave it empty, and default="" gives new rooms an empty topic.
• author is optional too, because anyone can chat without logging in: AuthMiddlewareStack in your asgi.py puts an anonymous user in the scope for them. If a user is deleted, their messages stay, with no author (SET_NULL).
• related_name="chat_messages" lets you write user.chat_messages. Plain messages would read as if it had to do with Django’s messages framework, which is also installed.
• Meta.ordering keeps every list of messages oldest first, the way a chat log reads.

You also deleted the chat/migrations/ folder in Part 1 of the Channels tutorial. Naming the app tells makemigrations to create it again:

uv run python manage.py makemigrations chat
uv run python manage.py migrate

You should see:

Migrations for 'chat':
  chat/migrations/0001_initial.py
    + Create model Room
    + Create model Message
Operations to perform:
  Apply all migrations: admin, auth, catalog, chat, contenttypes, sessions
Running migrations:
  Applying chat.0001_initial... OK

Your Channels tutorial also deleted chat/admin.py. Create it again, so you can look at rooms and messages in the admin site:

# chat/admin.py
from django.contrib import admin

from .models import Message, Room

admin.site.register(Room)
admin.site.register(Message)

Save messages from the consumer

The ChatConsumer you wrote in Part 3 of the Channels tutorial is asynchronous. As that page’s note said, an asynchronous consumer can still use Django models, through the model methods that start with a, like aget_or_create() and acreate(), as long as it calls channels.db.aclose_old_connections() before it uses the database. Put the following code in chat/consumers.py. The highlighted lines are new:

# chat/consumers.py
import json

from channels.db import aclose_old_connections
from channels.generic.websocket import AsyncWebsocketConsumer

from .models import Message, Room


class ChatConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        self.room_name = self.scope["url_route"]["kwargs"]["room_name"]
        self.room_group_name = f"chat_{self.room_name}"

        # Find the room in the database, or create it the first time anyone joins
        await aclose_old_connections()
        self.room, _ = await Room.objects.aget_or_create(name=self.room_name)

        # Join room group
        await self.channel_layer.group_add(self.room_group_name, self.channel_name)

        await self.accept()

    async def disconnect(self, close_code):
        # Leave room group
        await self.channel_layer.group_discard(self.room_group_name, self.channel_name)

    # Receive message from WebSocket
    async def receive(self, text_data):
        text_data_json = json.loads(text_data)
        message = text_data_json["message"]

        # Save the message before anyone sees it
        await aclose_old_connections()
        user = self.scope["user"]
        await Message.objects.acreate(
            room=self.room,
            author=user if user.is_authenticated else None,
            content=message,
        )

        # Send message to room group
        await self.channel_layer.group_send(
            self.room_group_name, {"type": "chat.message", "message": message}
        )

    # Receive message from room group
    async def chat_message(self, event):
        message = event["message"]

        # Send message to WebSocket
        await self.send(text_data=json.dumps({"message": message}))

• aget_or_create() returns a (room, created) tuple. The first person to open /chat/lobby/ creates the lobby room, and everyone after that joins the same row. The consumer keeps the room in self.room for as long as the WebSocket is open.
• self.scope["user"] is the user that AuthMiddlewareStack found, the same as request.user in a view. If you’re logged in, for example at /accounts/login/ from Prep 06, your messages get you as their author. Otherwise they’re saved with no author.
• The message is saved before it’s sent to the group. If saving fails, nobody sees a message that won’t be there when they reload the page.

Show a room’s history

Saved messages are only useful if you can see them. Update the room view in chat/views.py to load the room’s messages:

# chat/views.py
from django.shortcuts import render

from .models import Room


def index(request):
    return render(request, "chat/index.html")


def room(request, room_name):
    room = Room.objects.filter(name=room_name).first()
    chat_messages = room.messages.all() if room else []
    return render(
        request,
        "chat/room.html",
        {"room_name": room_name, "chat_messages": chat_messages},
    )

The context variable is called chat_messages, not messages. Django’s messages framework already puts a messages variable in every template’s context, and yours would hide it.

The view doesn’t create the room: opening the page isn’t enough to make a room, but connecting the WebSocket is. If the room doesn’t exist yet, there’s no history to show.

In chat/templates/chat/room.html, change only the textarea line, so that it starts with one line per saved message:

<!-- chat/templates/chat/room.html -->
<textarea id="chat-log" cols="100" rows="20">{% for chat_message in chat_messages %}{{ chat_message.content }}
{% endfor %}</textarea><br>

That’s the same format the JavaScript in the page uses when a new message arrives: the message, then a newline. The line break inside the for loop is that newline, so keep it exactly where it is, and don’t add spaces or line breaks anywhere else between the textarea tags. In particular, the {% endfor %} line must start at the very beginning of the line, even though the rest of the file is indented: any spaces before it would end up at the start of every message but the first.

Try it

Make sure Redis is running (see Part 2 of the Channels tutorial), then start the server:

uv run python manage.py runserver

Open http://127.0.0.1:8000/chat/lobby/ 🔗 in two tabs, and send “hello” and “anyone here?” from one of them. Both show up in both tabs, as before. Now reload a tab: the messages are still there.

Go to http://127.0.0.1:8000/admin/chat/message/ 🔗 and log in with your superuser. Your messages are listed there, and the lobby room is under Rooms. Messages you sent while logged in show your username as their author.

Finally, run the Channels tutorial’s tests again, to make sure the chat still works end to end:

uv run python manage.py test chat.tests

The rest of this page is about Django Ninja again. Join two or three more rooms, such as books and random, so the API has a few rooms to work with.

Schemas

A schema describes the shape of data going in or out of your API. Django Ninja schemas are Pydantic models: a class with type-annotated fields.

# locallibrary_config/api.py
from datetime import datetime

from ninja import Schema


class RoomIn(Schema):
    name: str
    topic: str = ""


class RoomOut(Schema):
    id: int
    name: str
    topic: str
    created_at: datetime

RoomIn is what clients send, and RoomOut is what they get back. They’re separate so a client can’t set id or created_at (or, later, fields you’d rather keep private). topic has a default, so it’s optional in RoomIn.

A schema doesn’t have to match a model. You’ll use plain Schema classes for anything that isn’t a table: login payloads, computed results, aggregates.

The same, generated from the model

When a schema mirrors a model, as these do, it only repeats what the model already says. ModelSchema reads the fields from the model instead:

# locallibrary_config/api.py
from ninja import ModelSchema

from chat.models import Room


class RoomIn(ModelSchema):
    class Meta:
        model = Room
        fields = ["name", "topic"]


class RoomOut(ModelSchema):
    class Meta:
        model = Room
        fields = ["id", "name", "topic", "created_at"]

These two classes behave the same as the hand-written ones, with the types and the topic default taken from the model. You also get the model’s constraints: name is limited to 50 characters because of max_length=50. When you add or change a model field, the schema follows.

The rest of this Quick Start uses the ModelSchema versions. You can mix both kinds freely, and a ModelSchema can also declare extra fields of its own (see ModelSchema).

Read: list and detail

Use response= to tell Django Ninja what an endpoint returns:

# locallibrary_config/api.py
from django.shortcuts import get_object_or_404


@api.get("/rooms", response=list[RoomOut])
def list_rooms(request):
    return Room.objects.all()


@api.get("/rooms/{room_id}", response=RoomOut)
def get_room(request, room_id: int):
    return get_object_or_404(Room, id=room_id)

• You return querysets and model instances directly. Django Ninja reads the fields listed in the schema and serializes them to JSON. There’s no serializer to call.
• {room_id} in the path becomes the room_id: int argument, converted and validated like the query parameters on the previous page.
• Django’s get_object_or_404 works as usual: a missing room is a 404 JSON response.
• Only the fields in RoomOut are sent back, even if the object has more. The schema is also the contract shown in the docs.

GET /api/rooms/1:

{
    "id": 1,
    "name": "lobby",
    "topic": "",
    "created_at": "2026-10-19T14:02:11.482Z"
}

Create, update, delete

A schema-typed argument is read from the JSON request body. The highlighted lines are the ones explained below:

# locallibrary_config/api.py
@api.post("/rooms", response={201: RoomOut})
def create_room(request, payload: RoomIn):
    return Room.objects.create(**payload.dict())


@api.put("/rooms/{room_id}", response=RoomOut)
def update_room(request, room_id: int, payload: RoomIn):
    room = get_object_or_404(Room, id=room_id)
    for attr, value in payload.dict().items():
        setattr(room, attr, value)
    room.save()
    return room


@api.delete("/rooms/{room_id}", response={204: None})
def delete_room(request, room_id: int):
    get_object_or_404(Room, id=room_id).delete()

• payload: RoomIn means “parse the body as RoomIn”. By the time your function runs, the data is valid and typed.
• response={201: RoomOut} maps a status code to a schema. With only one code listed, that’s the code every response gets, so create_room returns 201 and delete_room returns 204 with an empty body.
• update_room mixes a path parameter and a body in one signature. Django Ninja works out where each argument comes from.
• Deleting a room also deletes its messages, because of on_delete=models.CASCADE on Message.room.

Send a bad body, such as {"topic": 42}, and the error lists every problem at once:

{
    "detail": [
        {"type": "missing", "loc": ["body", "payload", "name"], "msg": "Field required"},
        {"type": "string_type", "loc": ["body", "payload", "topic"], "msg": "Input should be a valid string"}
    ]
}

Open /api/docs again. All five room endpoints are there, with request and response schemas, and you can create a room from the browser with Try it out. A room you create there is a real room: open /chat/<its name>/ and chat in it.

More than one status code

Try creating a room called lobby with Try it out. You get a 500 error, not a helpful answer: the name column is unique, so the database refuses the second lobby with an IntegrityError.

When an endpoint can answer in different ways, list every status code in response and return Status(code, data) to pick one. Replace create_room with a version that creates a room, or reports a clash with an existing one:

# locallibrary_config/api.py
from ninja import Schema, Status


class Conflict(Schema):
    message: str
    existing_id: int


@api.post("/rooms", response={201: RoomOut, 409: Conflict})
def create_room(request, payload: RoomIn):
    existing = Room.objects.filter(name=payload.name).first()
    if existing:
        return Status(409, {"message": "A room with that name already exists", "existing_id": existing.id})
    return Status(201, Room.objects.create(**payload.dict()))

Each response is validated against the schema for its code, and both appear in the interactive docs. See Responses for more.

(Renaming a room to a name that’s taken with PUT has the same problem. Fixing update_room the same way is a good exercise.)

Pagination

A list endpoint that returns every row won’t last long in production. Add one decorator:

# locallibrary_config/api.py
from ninja.pagination import paginate


@api.get("/rooms", response=list[RoomOut])
@paginate
def list_rooms(request):
    return Room.objects.all()

The view still returns a plain queryset. @paginate adds limit and offset query parameters, slices the queryset in the database, and wraps the result:

{
    "items": [{"id": 1, "name": "lobby", ...}],
    "count": 3
}

Page-number and cursor pagination, or your own class, are one argument away. See Pagination.

Filtering

Filters are also a schema: a FilterSchema, read from the query string. Each field maps to an ORM lookup:

# locallibrary_config/api.py
from datetime import timedelta
from typing import Annotated

from django.db.models import Q
from django.utils import timezone
from ninja import FilterLookup, FilterSchema, Query

...


class RoomFilter(FilterSchema):
    search: Annotated[str | None, FilterLookup("name__icontains")] = None
    topic: Annotated[str | None, FilterLookup("topic__icontains")] = None
    recent: bool | None = None

    def filter_recent(self, value: bool) -> Q:
        week_ago = timezone.now() - timedelta(days=7)
        return Q(created_at__gte=week_ago) if value else Q(created_at__lt=week_ago)


@api.get("/rooms", response=list[RoomOut])
@paginate
def list_rooms(request, filters: Query[RoomFilter]):
    return filters.filter(Room.objects.order_by("name"))

• search and topic map to icontains lookups on the room’s name and topic.
• recent needs custom logic, so a filter_recent method returns a Q object: rooms created in the last week, or, with recent=false, the ones before that.
• Filters left out of the request are skipped, and everything is validated. ?recent=maybe gets a 422, not a server error.

Now these all work, and combine with pagination:

/api/rooms?search=lob
/api/rooms?recent=true&topic=books
/api/rooms?recent=true&limit=10&offset=20

See Filtering for combining filters with OR, filtering on related models, and more.

What you have so far

Saved chat messages, plus about 60 lines of code that give you a paginated, filterable, validated and documented CRUD API:

Right now, though, anyone can create or delete rooms, and the API can’t show or post messages. Next: Auth, Routers & Next Steps.

2.3 - Quick Start Part 3: Auth, Routers & Next Steps

The rooms API works, but it all lives in one file and anyone can change data. On this page you’ll move the endpoints into the chat app, require login for writes, and let signed-in users post messages that show up in the chat page right away.

Move the endpoints into a router

A Router is a group of endpoints that you mount on the API under a prefix, much like Django’s include(). Each app can own its endpoints and the project just wires them together.

First, move the schemas to chat/schemas.py, unchanged: RoomIn, RoomOut, Conflict and RoomFilter. Then chat/api.py gets the endpoints, with @api replaced by @router and /rooms dropped from the paths:

# chat/api.py
from ninja import Router

router = Router(tags=["rooms"])


@router.get("/", response=list[RoomOut])
@paginate
def list_rooms(request, filters: Query[RoomFilter]):
    ...


@router.get("/{room_id}", response=RoomOut)
def get_room(request, room_id: int):
    ...

# ... and the rest

The chat app now has both chat/views.py, with the views for its HTML pages, and chat/api.py, with its API endpoints. They don’t interfere: chat/urls.py routes to the views, and the API routes to the router.

locallibrary_config/api.py is now only wiring. The hello and add endpoints from page 1 were only for practice, so they go too:

# locallibrary_config/api.py
from ninja import NinjaAPI

from chat.api import router as rooms_router

api = NinjaAPI()

api.add_router("/rooms", rooms_router)

The router’s / becomes /api/rooms/ and /{room_id} becomes /api/rooms/{room_id}. Note the trailing slash on the list: from now on, list and create rooms at /api/rooms/. A GET of /api/rooms still works, because Django redirects it to /api/rooms/, but a POST to it fails, because Django can’t redirect a POST. Thanks to tags=["rooms"], the interactive docs now group these endpoints under a rooms heading. Routers can be nested, and each one can carry its own auth, tags and other settings. See Routers.

Messages

The original Quick Start adds a model here for “user X is going to event Y”. Your chat already has its counterpart, “user X said Y in room Z”: the Message model from page 2. All it needs is schemas. Add them to chat/schemas.py, with Message added to its model import, and the room nested inside each message:

# chat/schemas.py
class MessageIn(ModelSchema):
    class Meta:
        model = Message
        fields = ["content"]


class MessageOut(ModelSchema):
    room: RoomOut

    class Meta:
        model = Message
        fields = ["id", "author", "content", "created_at"]

Declaring room: RoomOut tells Django Ninja to serialize the related Room with RoomOut, instead of returning only its id. author isn’t declared, so it comes back the default way for a foreign key: as the user’s id, or null for a message posted by someone who wasn’t logged in.

Require login

Turn on auth for the whole API in locallibrary_config/api.py:

# locallibrary_config/api.py
from ninja import NinjaAPI
from ninja.security import django_auth

from chat.api import router as rooms_router

api = NinjaAPI(auth=django_auth)

api.add_router("/rooms", rooms_router)

Every endpoint now requires a logged-in user, so you have to opt the public ones back out. Here’s the complete chat/api.py:

# chat/api.py
from asgiref.sync import async_to_sync
from channels.layers import get_channel_layer
from django.shortcuts import get_object_or_404
from ninja import Query, Router, Status
from ninja.errors import HttpError
from ninja.pagination import paginate

from .models import Message, Room
from .schemas import Conflict, MessageIn, MessageOut, RoomFilter, RoomIn, RoomOut

router = Router(tags=["rooms"])


@router.get("/", response=list[RoomOut], auth=None)
@paginate
def list_rooms(request, filters: Query[RoomFilter]):
    return filters.filter(Room.objects.order_by("name"))


@router.get("/mine", response=list[MessageOut])
def my_messages(request):
    return Message.objects.filter(author=request.auth).select_related("room")


@router.get("/{room_id}", response=RoomOut, auth=None)
def get_room(request, room_id: int):
    return get_object_or_404(Room, id=room_id)


@router.post("/", response={201: RoomOut, 409: Conflict})
def create_room(request, payload: RoomIn):
    existing = Room.objects.filter(name=payload.name).first()
    if existing:
        return Status(409, {"message": "A room with that name already exists", "existing_id": existing.id})
    return Status(201, Room.objects.create(**payload.dict()))


@router.put("/{room_id}", response=RoomOut)
def update_room(request, room_id: int, payload: RoomIn):
    room = get_object_or_404(Room, id=room_id)
    for attr, value in payload.dict().items():
        setattr(room, attr, value)
    room.save()
    return room


@router.delete("/{room_id}", response={204: None})
def delete_room(request, room_id: int):
    get_object_or_404(Room, id=room_id).delete()


@router.get("/{room_id}/messages", response=list[MessageOut], auth=None)
@paginate
def list_messages(request, room_id: int):
    room = get_object_or_404(Room, id=room_id)
    return room.messages.select_related("room")


@router.post("/{room_id}/messages", response={201: MessageOut})
def post_message(request, room_id: int, payload: MessageIn):
    room = get_object_or_404(Room, id=room_id)
    if not payload.content.strip():
        raise HttpError(400, "Messages can't be blank")
    message = Message.objects.create(room=room, author=request.auth, content=payload.content)
    # Send it to everyone in the room's chat page, the way ChatConsumer.receive does
    async_to_sync(get_channel_layer().group_send)(
        f"chat_{room.name}", {"type": "chat.message", "message": message.content}
    )
    return message

What’s new:

• NinjaAPI(auth=django_auth) requires a logged-in Django user for every endpoint, so new endpoints are protected unless you say otherwise. django_auth uses the regular Django session, the same one the admin and your catalog’s login pages use.
• auth=None opts the three read endpoints back out, so anyone can browse rooms and read their messages, just as anyone can open a chat page. Auth can be set on the whole API, on a router (Router(auth=...)) or on a single endpoint, and the most specific one wins.
• request.auth is whatever the authenticator returned. For django_auth that’s the User. my_messages lists the messages you posted, from the chat page while logged in or through the API, each with its room nested inside.
• HttpError(400, "...") stops the request and returns that status with a JSON {"detail": "..."} body. There’s no need to build error responses by hand.
• list_messages returns the messages oldest first, thanks to Meta.ordering on Message, and pages them with @paginate. select_related("room") fetches each message’s room in the same query, since MessageOut nests it.
• post_message sends the new message to the room’s group on the channel layer, exactly like ChatConsumer.receive does. Every ChatConsumer in that room receives the chat.message event, and its chat_message method sends the message to its browser. The view is synchronous and channel layer methods are asynchronous, so it calls them through async_to_sync, like your first, synchronous consumer did in Part 2 of the Channels tutorial. That means Redis must be running for post_message to work.

An anonymous request to a protected endpoint gets a 401:

$ curl http://127.0.0.1:8000/api/rooms/mine
{"detail": "Unauthorized"}

To try it out, make sure Redis is running, log in at /admin/ (or at /accounts/login/, from Prep 06), and open /api/docs. Swagger UI reuses your session and sends the CSRF token for you, so you can post a message with Try it out.

In a second tab, open the chat page for the room you’ll post to, such as http://127.0.0.1:8000/chat/lobby/ 🔗. Find its id with GET /api/rooms/?search=lobby. Then, back in the docs, POST /api/rooms/1/messages (with your room’s id) and the body {"content": "hello from the API"}. The message appears in the chat tab right away, and the response has the nested schema:

{
    "room": {
        "id": 1,
        "name": "lobby",
        "topic": "",
        "created_at": "2026-10-19T14:02:11.482Z"
    },
    "id": 7,
    "author": 1,
    "content": "hello from the API",
    "created_at": "2026-10-19T15:21:40.913Z"
}

Your message and user ids will be different. Post {"content": " "} and you get 400 {"detail": "Messages can't be blank"}.

What you’ve built

In three pages, and without writing any serializers, URL patterns or docs by hand, you have a chat that remembers its messages, and an API with:

• typed, validated path, query and body parameters,
• schemas generated from Django models, including a nested one,
• full CRUD, pagination and filtering,
• session auth with public and protected endpoints,
• proper error responses,
• messages posted through the API that reach the chat page live, and
• interactive OpenAPI docs that always match the code.

Where to go next

Our Django Ninja Tutorial builds a larger project step by step, in your locallibrary next to everything you’ve built so far. The Guide covers each feature in depth. Here’s where to read more about everything used in this Quick Start:

Features you haven’t seen yet: async views, throttling, API versioning, custom renderers and a test client.

3 - Django Ninja Tutorial

This tutorial builds one realistic API from start to finish: TaskFlow, a task tracker for teams. Users sign up, create projects, invite members with roles, and track tasks with assignees, labels, statuses, due dates, comments and file attachments. Each part adds a feature to the same codebase and shows the Django Ninja tools that make it work.

What you’ll build

By the end of Part 8, TaskFlow has these endpoints:

Every endpoint except the auth ones needs a token, and users only ever see the projects they’re members of. A second version of the API runs next to the first at /taskflow/api/v2/, and a pytest suite covers the rules that matter.

Before you start

• You know Django: projects, apps, models, migrations and settings. The tutorial doesn’t explain those. It focuses on the Django Ninja parts.
• You’ve done our Django Ninja Quickstart, so NinjaAPI, schemas and the interactive docs are familiar. That also means you’ve finished preps 01-06 and our Channels tutorial, and you have your locallibrary repository: a uv project with manage.py, pyproject.toml, and uv.lock at its root, the locallibrary_config project package, and the catalog and chat apps. Every command in this tutorial is run from that root folder.
• You have Python 3.12 or newer. The code uses modern type hints such as int | None and list[int]. Your locallibrary uses Python 3.14.

The only packages TaskFlow needs are Django and Django Ninja, and both are already in your pyproject.toml: Django since Prep 01, and Django Ninja since the Quickstart. You can check:

uv run python -c "import django, ninja; print(django.__version__, ninja.__version__)"

Everything else, including JSON Web Tokens, is written with the standard library. Part 7 adds pytest and pytest-django as development tools. The database is the same SQLite db.sqlite3 your catalog and chat use, and all of TaskFlow’s views are synchronous.

How the parts work

• Each part starts with a What you’ll learn box and takes about 15 minutes to read and type.
• Each part builds on the code of the one before, so work through them in order. Changed files are shown in full, or as excerpts with ... where the rest of the file stays the same.
• The example requests and responses are real output from the original tutorial. Your projects, labels, tasks, comments and attachments get new tables, so if you follow along exactly, their ids will match the ones on the pages. Your user ids won’t, because your database already has users. Part 2 explains what to do about that.
• Go deeper links at the end of each section point to the Django Ninja Guide page that covers the feature in full.

The parts

1. Project setup & layout: one router per app, schemas from models, and task URLs nested under projects.
2. Relations & computed fields: assignees and labels as nested output, computed and annotated fields, and fewer queries.
3. Validation & workflows: status and priority choices, field and model validators, PATCH updates and status transitions.
4. Auth & permissions: JWT tokens from scratch, project memberships with roles, and object-level rules for comments.
5. Filtering, search, ordering & pagination: a FilterSchema for tasks, safe sort orders, and page-number and cursor pagination.
6. File uploads & forms: multipart uploads with form fields, file validation, media files and absolute URLs.
7. Testing: a pytest suite with fixtures and TestClient, covering validation, permissions, filters and uploads.
8. OpenAPI polish & versioning: descriptions, examples and deprecations in the docs, and a version 2 next to version 1.

Ready? Start with Part 1: Project setup & layout.

How this copy differs from the original

This is a copy of the official Django Ninja tutorial, changed to match the way we have worked in our fork of the MDN Django Tutorial, our Channels tutorial, and our Django Ninja Quickstart:

• You don’t create a new project. The projects, tasks, and accounts apps go into your existing locallibrary repository, next to catalog and chat. Everywhere the original edits taskflow/settings.py or taskflow/urls.py, this copy edits locallibrary_config/settings.py or locallibrary_config/urls.py, and only adds lines.
• taskflow is a plain package. In the original, taskflow is the Django project package. Here it’s a small package next to manage.py that holds only taskflow/api.py, so imports like from taskflow.api import api work exactly as in the original.
• TaskFlow lives at /taskflow/api/, not /api/. Your Quickstart API already uses /api/. Every TaskFlow URL in this copy starts with /taskflow/api/, and version 2 is at /taskflow/api/v2/. Paths inside TestClient calls are relative to the API, so they’re the same as in the original.
• Each TaskFlow NinjaAPI sets urls_namespace=. That keeps TaskFlow’s URL names apart from the Quickstart API’s. Part 8 explains why.
• Dependencies are managed with uv. pip install becomes uv add (uv add --dev for pytest), and every command is run with uv run.
• You never delete db.sqlite3. The original suggests it in Part 2 so the ids match. Yours holds your catalog and chat data, so this copy looks users up by username where the original uses their ids.
• Part 6 adds media/ to your .gitignore. The original assumes it’s already there.
• Part 7’s tests use your test_db.sqlite3 file. That’s the TEST database setting you added in Part 4 of the Channels tutorial.

This copy follows the Django Ninja documentation as of 2026-10-19 (Django Ninja 1.7.1), on Django 6.1 and Python 3.14.

The original tutorial is Copyright (c) 2025 Vitaliy Kucheryaviy, and is used under its MIT license.

3.1 - Part 1: Project setup & layout

Over eight parts, you’ll build TaskFlow, a task tracker for teams: projects, members, tasks, labels, comments and file attachments. This first part sets up a project layout that stays tidy as the API grows. Each app gets its own router and schemas, and one small module wires them together.

Create the apps

You don’t create a new project: TaskFlow goes into your existing locallibrary repository, next to catalog and chat. Django and Django Ninja are already in your pyproject.toml from the Django Ninja Quickstart, so there’s nothing to install. From the folder with manage.py, create the two apps:

uv run python manage.py startapp projects
uv run python manage.py startapp tasks

TaskFlow doesn’t use Django’s template views, so you can delete views.py and tests.py from both apps. The tests come back in Part 7, in their own place.

In the original tutorial, taskflow is the name of the Django project package, the folder with settings.py and urls.py. Yours is called locallibrary_config, and you’ll keep it. TaskFlow still gets a taskflow package of its own, though, to hold the module that wires its routers together. It’s a plain Python package, not an app, so create it by hand: a taskflow folder next to manage.py, with an empty __init__.py file inside.

Register the two apps in locallibrary_config/settings.py, at the end of INSTALLED_APPS. 'ninja' is already there from the Quickstart. Don’t remove anything:

# locallibrary_config/settings.py
INSTALLED_APPS = [
    'daphne',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'catalog.apps.CatalogConfig',
    'chat',
    'ninja',
    'projects',
    'tasks',
]

'ninja' is optional. With it, runserver serves the Swagger UI assets locally instead of from a CDN.

When this part is done, the new parts of your locallibrary will look like this:

catalog/            # (unchanged)
chat/               # (unchanged)
locallibrary_config/
├── settings.py
└── urls.py         # mounts the TaskFlow API next to the Quickstart's
taskflow/
├── __init__.py
└── api.py          # NinjaAPI: wires the routers together
projects/
├── api.py          # Router with the project endpoints
├── models.py
└── schemas.py
tasks/
├── api.py          # Router with the task endpoints
├── models.py
└── schemas.py
manage.py

The pattern is the same for every app: models in models.py, schemas in schemas.py, endpoints in api.py. The taskflow package holds only the wiring.

Models

A project, and a task that belongs to one:

# projects/models.py
from django.db import models


class Project(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

# tasks/models.py
from django.db import models

from projects.models import Project


class Task(models.Model):
    project = models.ForeignKey(Project, related_name="tasks", on_delete=models.CASCADE)
    title = models.CharField(max_length=200)
    description = models.TextField(default="")
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title

$ uv run python manage.py makemigrations
Migrations for 'projects':
  projects/migrations/0001_initial.py
    + Create model Project
Migrations for 'tasks':
  tasks/migrations/0001_initial.py
    + Create model Task
$ uv run python manage.py migrate

Tasks will get assignees, labels, a status and more in later parts. For now, a title is enough.

Schemas

Each app keeps its schemas in schemas.py. As in the Quick Start, there’s an In schema for what clients send and an Out schema for what they get back:

# projects/schemas.py
from ninja import ModelSchema

from .models import Project


class ProjectIn(ModelSchema):
    class Meta:
        model = Project
        fields = ["name", "description"]


class ProjectOut(ModelSchema):
    class Meta:
        model = Project
        fields = ["id", "name", "description", "created_at"]

ProjectIn is generated entirely from the model. Neither name nor description has a default, so both are required.

The task schemas follow the same pattern:

# tasks/schemas.py
from ninja import ModelSchema

from .models import Task


class TaskIn(ModelSchema):
    class Meta:
        model = Task
        fields = ["title", "description"]


class TaskOut(ModelSchema):
    class Meta:
        model = Task
        fields = ["id", "project", "title", "description", "created_at"]

Task.description has default="", so TaskIn makes it optional, with an empty string as the default. TaskIn has no project field. The project comes from the URL, as you’ll see below. In TaskOut, the project foreign key is serialized as the project’s id. Part 2 replaces ids like this with nested objects where that helps.

Go deeper: ModelSchema

The projects router

Each app’s endpoints live on a Router in the app’s api.py. Here’s full CRUD for projects:

# projects/api.py
from django.shortcuts import get_object_or_404
from ninja import Router, Status

from .models import Project
from .schemas import ProjectIn, ProjectOut

router = Router(tags=["projects"])


@router.get("/", response=list[ProjectOut])
def list_projects(request):
    return Project.objects.order_by("id")


@router.post("/", response={201: ProjectOut})
def create_project(request, payload: ProjectIn):
    return Status(201, Project.objects.create(**payload.dict()))


@router.get("/{project_id}", response=ProjectOut)
def get_project(request, project_id: int):
    return get_object_or_404(Project, id=project_id)


@router.put("/{project_id}", response=ProjectOut)
def update_project(request, project_id: int, payload: ProjectIn):
    project = get_object_or_404(Project, id=project_id)
    for attr, value in payload.dict().items():
        setattr(project, attr, value)
    project.save()
    return project


@router.delete("/{project_id}", response={204: None})
def delete_project(request, project_id: int):
    get_object_or_404(Project, id=project_id).delete()
    return Status(204, None)