Deploy Django with ASGI

Django supports deploying on ASGI, the emerging Python standard for asynchronous web servers and applications. The startproject command sets up a minimal default WSGI configuration for you that you can tweak as needed.

The application Object

Like WSGI, ASGI requires an application callable. Web servers use this callable to communicate with your code. When you start a project, Django creates a asgi.py file containing this exact object. While the standard Django development server does not use this file, any ASGI-compliant server can use it in both development and production.

ASGI servers typically require the path to this application callable as a string. For a standard Django project, this path looks like <project_name>.asgi:application.

Note that Django's default ASGI handler runs your code in a synchronous thread. If you write your own asynchronous handler, you must ensure it is async-safe. You cannot call blocking synchronous functions inside asynchronous code.

Configuring the Settings Module

When an ASGI server loads your application, Django needs to import your settings module to understand how your project is configured. Django uses the DJANGO_SETTINGS_MODULE environment variable to locate this file.

If this variable is not set, the default asgi.py file automatically sets it to mysite.settings (where mysite is your project name).

Applying ASGI Middleware

You can apply ASGI middleware or embed Django inside another ASGI application by wrapping the Django application object in your asgi.py file.

from some_asgi_library import AmazingMiddleware

# Wrap the default Django application
application = AmazingMiddleware(application)

Deploying with Daphne

Daphne is a pure-Python ASGI server for UNIX. Members of the Django project maintain it and it serves as the reference server for ASGI.

You install Daphne using pip.

python -m pip install daphne

Once installed, you can start the server by calling the daphne command with the path to your ASGI application. You must run this command from the same directory as your manage.py file to ensure your project is on the Python path.

daphne mysite.asgi:application

This will start one process listening on 127.0.0.1:8000.

Daphne also integrates with Django's runserver command for development. You can enable this by adding daphne to the very top of your INSTALLED_APPS list and adding an ASGI_APPLICATION setting pointing to your application object.

INSTALLED_APPS = [
    "daphne",
    # other apps
]
ASGI_APPLICATION = "mysite.asgi.application"

Deploying with Hypercorn

Hypercorn is an ASGI server that emphasizes protocol support. It supports HTTP/1, HTTP/2 and HTTP/3 connections.

You install Hypercorn using pip:

python -m pip install hypercorn

You start the server by calling the hypercorn command followed by the location of your ASGI application. You must run this command from the same directory as your manage.py file to ensure your project is on the Python path.

hypercorn mysite.asgi:application

This will start one process listening on 127.0.0.1:8000.

Deploying with Uvicorn

Uvicorn is an ASGI server built for speed. It is based on uvloop and httptools.

You install Uvicorn using pip:

python -m pip install uvicorn

You can start the server by invoking Uvicorn through Python and passing the path to your ASGI application. You must run this command from the same directory as your manage.py file to ensure your project is on the Python path. During development, you can add a --reload flag to make the server automatically restart whenever you change a file.

python -m uvicorn mysite.asgi:application --reload

For production environments, it is common to run Uvicorn behind Gunicorn. Gunicorn is a robust web server that provides process monitoring and automatic restarts. You install both tools and the Uvicorn worker package using pip:

python -m pip install uvicorn uvicorn-worker gunicorn

You then start Gunicorn and tell it to use the Uvicorn worker class:

python -m gunicorn mysite.asgi:application -k uvicorn_worker.UvicornWorker