Deployment

Gunicorn ("Green Unicorn") is a pure-Python, UNIX-only server with a pre-fork model: an arbiter process opens the listening socket, forks workers, restarts any that die or hang, and reacts to signals. It is the most common choice for a synchronous Django project. The simplest invocation, from the directory containing manage.py, starts one process with one thread on 127.0.0.1:8000:

Source: How to use Django with Gunicorn

One worker is a development setting. For production, put the options in gunicorn.conf.py, which Gunicorn reads from the current directory, so the command line stays short and the configuration lives in version control (without secrets):

Source: Gunicorn: Configure, Gunicorn: Settings and Gunicorn: Design

The log lines are shortened (timestamps and PIDs removed). The settings that matter for Django:

Gunicorn is controlled with signals: HUP reloads the configuration and replaces the workers gracefully, TERM shuts down gracefully (waiting up to graceful_timeout), TTIN/TTOU add or remove a worker. The scratch run below binds a UNIX socket, as Gunicorn would behind NGINX on the same machine, and sends HUP; the second request is served by the new workers:

Source: Gunicorn: Signal handling and Gunicorn: Deploying Gunicorn

The socket path is shortened (the scratch run used a temporary directory). On a VM, systemd supervises the arbiter. Gunicorn’s deployment guide gives a unit file; adapted for Bookshelf with an environment file that only root and the service user can read, it looks like this (not run: the test machine has no systemd):

Source: Gunicorn: Deploying Gunicorn (systemd) and systemd.exec

EnvironmentFile= holds the DJANGO_* variables of The running example; TimeoutStopSec is a little above graceful_timeout so systemd does not kill workers that are finishing requests. RuntimeDirectory= creates /run/bookshelf owned by the service user, where the socket goes.

Granian is an HTTP server written in Rust (on top of Hyper and Tokio, the same stack as the Axum framework) that runs Python applications over WSGI, ASGI or its own RSGI interface. Django’s how-to pages for both WSGI and ASGI gained a Granian page in the 6.1 documentation (the 5.2 and 6.0 versions have none). The interface must be named, because Granian’s default is RSGI, which Django does not implement:

Source: How to use Django with Granian (WSGI) and Granian documentation

Without --workers Granian starts one process on 127.0.0.1:8000, like the other servers. Every option also has a GRANIAN_* environment variable (GRANIAN_WORKERS, GRANIAN_HOST, GRANIAN_INTERFACE, …​), which suits container platforms. Options worth knowing for Django: --blocking-threads (threads per worker that run the synchronous WSGI application), --respawn-failed-workers, --workers-lifetime and --workers-max-rss (recycle workers by age or memory, the equivalent of Gunicorn’s max_requests), --url-path-prefix (when the site is mounted below /) and --static-path-route with --static-path-mount (Granian can serve STATIC_ROOT itself, an alternative to WhiteNoise when there is no proxy). Granian is younger than Gunicorn and its options change between minor releases, so pin it and read granian --help for the installed version.

uWSGI is a C application server with a very large feature set (process management, its own binary protocol for NGINX’s uwsgi_pass, caching, spoolers). Its documentation now opens with a notice that the project is in maintenance mode: bug fixes and updates for new language APIs only. Django still documents it and it still works, but it is no longer a sensible choice for a new project; existing deployments keep running, and a migration to Gunicorn or Granian is mostly a change of the process-manager configuration. For reference, an ini file in the form of Django’s example, with HTTP enabled so that curl can reach it directly (behind NGINX you would use socket and uwsgi_pass instead):

Source: How to use Django with uWSGI and The uWSGI project (maintenance-mode notice)

harakiri is uWSGI’s request timeout (Gunicorn’s timeout), max-requests recycles workers, vacuum removes sockets and PID files on exit, and env = LANG=en_US.UTF-8 is the fix Django’s page gives for UnicodeEncodeError on uploads with non-ASCII file names. pip install uwsgi compiles C code, so the build needs a compiler and Python headers.

mod_wsgi is an Apache module that hosts a WSGI application inside Apache. It suits organisations that already run Apache. Django recommends daemon mode, where the application runs in separate processes managed by mod_wsgi rather than inside Apache’s own workers; in daemon mode the import path goes in the python-path option instead of WSGIPythonPath. A virtual host for Bookshelf (not run: mod_wsgi was not available on the test machine):

Source: How to use Django with Apache and mod_wsgi and mod_wsgi documentation

The SECRET_KEY and other DJANGO_* variables do not reach a mod_wsgi daemon from a shell: pass them through the Apache service’s environment or read them from a file in wsgi.py before get_wsgi_application() runs. Apache serves the Alias paths itself, so no WhiteNoise is needed. Django also documents using mod_wsgi to authenticate other Apache-served resources against Django’s user database (django.contrib.auth.handlers.modwsgi), a niche but useful trick for protecting, say, a directory of downloads with Django accounts.

Source: How to authenticate against Django’s user database from Apache

Uvicorn is a fast ASGI server built on uvloop and httptools when they are installed (uvicorn[standard]). It has its own --workers option and process supervisor, so it no longer needs Gunicorn to run several processes, although Django’s page still shows that combination:

Source: How to use Django with Uvicorn and Uvicorn: Deployment

--proxy-headers makes Uvicorn use X-Forwarded-Proto and X-Forwarded-For for the ASGI scope’s scheme and client address, but only from the addresses in --forwarded-allow-ips (default 127.0.0.1,::1, or the FORWARDED_ALLOW_IPS environment variable). --workers defaults to the WEB_CONCURRENCY environment variable when it is set. --reload is for development only. To run Uvicorn’s worker class under Gunicorn’s arbiter (Gunicorn’s signals, max_requests and timeouts with Uvicorn’s protocol code), install the separate uvicorn-worker package; the old in-tree uvicorn.workers.UvicornWorker is deprecated in favour of it:

Source: Deploying Django using Uvicorn and Gunicorn and uvicorn-worker

Gunicorn itself gained a native ASGI worker in 24.0.0 (2026-01-23), announced as beta, with HTTP/1.1, WebSockets and the lifespan protocol, and its compatibility table lists "Django + Channels". Django’s documentation does not cover it yet. It ran the scratch project without problems:

Source: Gunicorn: ASGI Worker and Gunicorn changelog 2026

Daphne is a pure-Python ASGI server maintained by members of the Django project and is the reference ASGI server; it grew out of Channels. Its runserver integration lets you develop under ASGI with the usual command:

Source: How to use Django with Daphne and Daphne

daphne must come before django.contrib.staticfiles because both provide a runserver command and the first app wins; with it in the wrong place the check framework reports daphne.E001. Daphne’s --proxy-headers reads X-Forwarded-For (and optionally a port header) for the client address; it does not change the scheme, which Django takes from SECURE_PROXY_SSL_HEADER in any case. Daphne has no multi-process mode of its own: run one Daphne per container, or several behind a process manager. The Channels-specific deployment (Redis channel layer, worker processes) is in Channels & WebSockets.

Hypercorn emphasises protocol support: HTTP/1.1, HTTP/2 and HTTP/3 (QUIC), with asyncio or Trio workers. Browsers only use HTTP/2 and HTTP/3 over TLS, so that support matters when Hypercorn terminates TLS itself (--certfile, --keyfile, --quic-bind); behind a proxy that speaks HTTP/1.1 upstream, which is the usual NGINX setup, it behaves like the others:

Source: How to use Django with Hypercorn and Hypercorn documentation

The status line really is HTTP/1.1 200 with no reason phrase; HTTP/1.1 allows an empty one.

The same Granian binary runs the ASGI application when told to:

Source: How to use Django with Granian (ASGI) and Granian documentation

--interface asginl is a variant without the ASGI lifespan protocol. Django’s ASGI handler accepts only http connections and does not implement lifespan; servers in their default mode detect that and carry on (Uvicorn logs ASGI 'lifespan' protocol appears unsupported.), so either interface works.

None of the servers is a reason to switch interfaces: start with Gunicorn on WSGI unless the project has async views, streaming or WebSockets, and measure before tuning. Whatever the server, keep DEBUG off, run several workers or containers, and put the server behind a proxy or load balancer.

Source: How to deploy with WSGI, How to deploy with ASGI and the PyPI pages listed in References

Behind a TLS-terminating proxy, the application server receives plain HTTP. Unless something says otherwise, request.is_secure() is False for every request, which breaks three things at once: SECURE_SSL_REDIRECT redirects every request to HTTPS forever (the proxy forwards the HTTPS request as HTTP again), build_absolute_uri() produces http:// links, and CSRF’s strict Referer checking for HTTPS does not apply. Three settings close the gap:

Django’s settings reference lists the conditions under which SECURE_PROXY_SSL_HEADER is safe, and all must hold: the application is behind a proxy, the proxy strips X-Forwarded-Proto from incoming requests (including comma-separated lists), and the proxy sets it only for requests that really arrived over HTTPS. If any of these is false, a client can claim HTTPS by sending the header itself. The proxy_set_header line in the NGINX file satisfies the conditions; so do the managed load balancers of the major clouds, which set the header themselves. What breaks the guarantee is an application port that is reachable without going through the proxy.

The scratch project makes this observable. With the proxy settings on, a forwarded HTTPS request is secure, gets HSTS, and builds https:// URLs with the forwarded host; without a Host that is in ALLOWED_HOSTS the request is refused:

Source: SECURE_PROXY_SSL_HEADER, USE_X_FORWARDED_HOST and USE_X_FORWARDED_PORT

The server log for the last request shows Django’s DisallowedHost error: Invalid HTTP_HOST header: 'attacker.example'. You may need to add 'attacker.example' to ALLOWED_HOSTS.

The application servers have their own, separate trust setting, and it interacts with Django’s. Gunicorn sets the WSGI scheme to https when a request from an address in forwarded_allow_ips (default: localhost) carries X-Forwarded-Proto: https, and Django’s is_secure() honours that scheme even without SECURE_PROXY_SSL_HEADER. So with NGINX on the same host, the redirect loop does not appear even if you forget the Django setting; move NGINX to another host and it does:

Source: Gunicorn: Settings (forwarded_allow_ips, secure_scheme_headers) and Gunicorn: Deploying Gunicorn

The first run is what a proxy on another machine produces: the browser asked for HTTPS, the proxy forwarded HTTP, and Django sends it back to HTTPS indefinitely. Set SECURE_PROXY_SSL_HEADER explicitly rather than relying on the server’s behaviour, and list the proxy’s address in the server’s trust setting (--forwarded-allow-ips in Gunicorn and Uvicorn; Daphne’s --proxy-headers) so that client addresses in logs are right too. Two related settings: Django 4.0 made CSRF_TRUSTED_ORIGINS entries require a scheme (https://bookshelf.example.com), and they are only needed for origins other than the site’s own, such as a separate front end; and the security settings that depend on HTTPS (SECURE_SSL_REDIRECT, HSTS, secure cookies) are covered in HTTPS and, in depth, in Security.

check --deploy adds the checks tagged deploy to the normal system checks. It must run with the production settings (the same DJANGO_SETTINGS_MODULE and environment as the servers), otherwise it inspects the wrong configuration. On a project fresh from startproject in Django 6.1 it reports one error and seven warnings:

Source: check --deploy and System check framework: Security

The error is new in 6.1: startproject now writes a MAILERS setting with the console backend, and the deployment-only check mail.E001 refuses it, because a production site that silently prints its password-reset emails to a log is broken. With the Bookshelf settings and the production environment variables, the same command is clean even at the strictest useful level, which is how it should run in CI and in the release step:

Source: check --fail-level and Django 6.1 release notes (mail.E001)

By default the command exits non-zero only for errors, so warnings pass a pipeline unnoticed; --fail-level WARNING makes them fatal. A warning that does not apply (for example security.W008 on a site where the load balancer does the redirect) is silenced explicitly with SILENCED_SYSTEM_CHECKS = ["security.W008"] and a comment, never by ignoring the output. Melé’s book shows the warnings and moves on; that is exactly the habit the flag exists to break. The full list of deploy checks and how to write your own is in System Checks.

runserver is single-process, reloads on code changes, serves static files only with DEBUG, and has not been through a security audit. The production replacements are the servers in WSGI servers and ASGI servers.

SECRET_KEY signs sessions, password-reset tokens, messages and anything using django.core.signing. It must be long, random, unique to the environment, and never committed. The checklist offers the environment or a file:

Source: Deployment checklist: SECRET_KEY

To rotate a key without logging everybody out, move the old one into SECRET_KEY_FALLBACKS (Django 4.1+): values signed with a fallback still verify, new values are signed with the new key, and the old key is removed once sessions and tokens signed with it have expired. The Bookshelf settings read the list from DJANGO_SECRET_KEY_FALLBACKS:

Source: SECRET_KEY_FALLBACKS

The rotation procedure and the deploy checks on fallbacks are in Settings & Configuration.

DEBUG must never be True in production. With it on, every error page shows source excerpts, local variables and settings, Django records the recent SQL queries of each connection in memory, and an empty ALLOWED_HOSTS is accepted (local names only), which hides a missing production value. Setting it to False also switches on the cached template loader and makes runserver stop serving static files. The settings above default it to off, so forgetting the variable is safe.

ALLOWED_HOSTS. With DEBUG = False Django refuses every request whose Host (or, with USE_X_FORWARDED_HOST, X-Forwarded-Host) is not listed, with a 400 response. The list protects against host-header attacks, such as poisoned password-reset links built from an attacker’s Host. A wildcard (["*"]) switches that protection off; the checklist says that if you use one, you must validate the Host header yourself. The proxy should also filter hosts (the return 444 server above), so that junk never reaches Django’s logs. A leading dot matches a domain and its subdomains (.example.com). Platforms that probe containers by IP address need that address listed, or a health endpoint answered before host validation; it is simpler to make the platform send the real host name.

CACHES. The default is a per-process local-memory cache, so with four Gunicorn workers there are four caches that disagree. Production uses a shared cache (Redis or Memcached), and the checklist adds that cache servers often have weak authentication, so they must accept connections only from the application servers. The Bookshelf settings take the backend and location from the environment, for example DJANGO_CACHE_BACKEND=django.core.cache.backends.redis.RedisCache and DJANGO_CACHE_LOCATION=redis://cache:6379/1; see Caching.

DATABASES. Connection parameters differ per environment and the password is as sensitive as SECRET_KEY. The database should accept connections only from the application servers, and, in the checklist’s words, if you have not set up backups, "do it right now". PostgreSQL options, pooling and TLS to the database are in PostgreSQL & Database Backends.

MAILERS and related settings. In 6.1 the email configuration is the MAILERS dictionary (the EMAIL_* settings are deprecated). Development uses the console or file backend; production needs a real backend, which mail.E001 now enforces. Change DEFAULT_FROM_EMAIL and SERVER_EMAIL too: their defaults (webmaster@localhost, root@localhost) are rejected by many mail providers. See Email.

STATIC_ROOT and STATIC_URL. STATIC_ROOT must be set for collectstatic to have a destination (Static and media files in production).

MEDIA_ROOT and MEDIA_URL. Uploads are untrusted; the web server must never interpret them, and they need their own backups.

Source: Deployment checklist: Environment-specific settings and ALLOWED_HOSTS

Any site with logins must use HTTPS everywhere, not just on the login page: the session cookie is the same for HTTP and HTTPS, so one plain-HTTP request leaks it. The proxy redirects HTTP to HTTPS and forwards only HTTPS to Django, and then the checklist’s two settings, plus the three that check --deploy asks about, are switched on:

Source: Deployment checklist: HTTPS and HTTP Strict Transport Security

The Bookshelf settings tie the cookie flags to DEBUG and read the HSTS values from the environment, so a staging site can run without HSTS while production sends a year. The scratch run in Telling Django about the proxy: SECURE_PROXY_SSL_HEADER and friends shows the resulting Strict-Transport-Security header. HSTS is only sent on secure responses, which is another reason to get SECURE_PROXY_SSL_HEADER right. More on each header, CSP and the other SecurityMiddleware settings in Security and Content Security Policy.

DEBUG = False already disables development-only features. The checklist adds three tunings:

Source: Deployment checklist: Performance optimizations, Persistent connections and Using cached sessions

CONN_MAX_AGE is for WSGI, where each worker thread keeps its own connection; multiply workers, threads and hosts to see how many connections the database must accept. Under ASGI, persistent connections should be disabled (CONN_MAX_AGE = 0) and psycopg’s pool used instead (OPTIONS = {"pool": True}, Django 5.1+); the details are in PostgreSQL & Database Backends. Beyond the checklist, Performance & Optimization covers profiling and caching strategy.

LOGGING. Review it before going live and check it works once traffic arrives. In containers, log to standard output (the Bookshelf settings send the root logger to a StreamHandler) and let the platform collect it.

ADMINS and MANAGERS. With DEBUG = False, ADMINS receive an email for every 500 error and MANAGERS for broken links (404s with a referrer, when BrokenLinkEmailsMiddleware is installed); IGNORABLE_404_URLS filters the noise. The checklist itself warns that email reporting does not scale and suggests an error-monitoring service such as Sentry.

Error views. Django’s default 404.html, 500.html, 403.html and 400.html responses are plain. Templates of those names in a root template directory replace them; 500.html is rendered without a request context, so it must not depend on context processors or the database:

Source: Deployment checklist: Error reporting and Error views

The logging configuration, email reports with sensitive-data filtering, and Sentry are covered in Logging & Error Reporting.

The release step of the topology, as one script that fails on the first problem:

Source: migrate, collectstatic and Deployment checklist: Run manage.py check --deploy

Where collectstatic runs depends on the static strategy: with WhiteNoise in a container image it belongs in the image build (the files ship with the code); with a shared bucket, in the release step (once); with NGINX on each VM, on each host. After the script succeeds, the servers are restarted gracefully (systemctl reload bookshelf sends Gunicorn HUP) or the platform rolls out new containers.