Django

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This section is written against Django 6.1.1 (released 2026-09-02), checked on 2026-10-03; Django 6.1.2, a security and bug-fix release, is scheduled for 2026-10-06. Django 6.1 supports Python 3.12, 3.13 and 3.14, and PostgreSQL 15 or later, MySQL 8.4 or later, MariaDB 10.11 or later and SQLite 3.37 or later. Where the long-term support release Django 5.2 LTS (supported until April 2028) behaves differently, the pages say so.

Django’s support policy gives each feature release mainstream support (bug and security fixes) until the next feature release ships, roughly eight months later, followed by security fixes for roughly eight more months; every third release is a long-term support (LTS) release that receives security fixes for about three years. Django 6.1 receives mainstream support until April 2027 and security fixes until December 2027, and Django 6.0 is supported until April 2027. Django 6.2, due in April 2027, is the next LTS release and the last one under this scheme. Starting with the release planned for January 2028, named Django 2028, Django moves to calendar versioning (DEP 20) with one release per year, each supported for three years. Django 6.1 already renames its deprecation warnings accordingly: what used to be RemovedInDjango70Warning is now RemovedInDjango2028Warning. The What’s Changed & Upgrading page covers the timeline and how to keep a project current.

What Django is

Django is a free, open-source, "batteries-included" Python web framework, maintained by the Django Software Foundation since 2008 and in public development since 2005. A single installation provides everything a database-backed web site needs:

an object-relational mapper (ORM) with schema migrations
URL routing, function-based and class-based views, middleware and the request/response objects
a template language with inheritance, partials and automatic HTML escaping
forms with validation and rendering, including forms generated from models
an automatic, customisable admin interface
authentication, permissions, sessions, and protection against CSRF, XSS, clickjacking and SQL injection, plus a built-in Content Security Policy since Django 6.0
caching, email, a background tasks framework (django.tasks, Django 6.0), signals, logging, internationalisation, localisation and time zones, pagination and system checks
contrib apps for content types, sites, sitemaps, syndication feeds, flat pages, redirects and GeoDjango
WSGI and ASGI deployment, with async views, async ORM methods and async authentication helpers

Django follows a model-template-view (MTV) split: models describe data, views decide what to return, and templates render it. Its design philosophies (loose coupling, less code, "don’t repeat yourself", explicit over implicit) are described on the Introduction & Architecture page.

This section is for developers who:

know Python (or come from Flask, FastAPI, Spring Boot, ASP.NET Core, Laravel or Rails) and want to build and run server-rendered sites, admin-heavy back offices, content sites or JSON APIs with Django
want one coherent path from a first project to testing, security, background work, real-time features, deployment and upgrades
learned Django from older books and tutorials (the 1.11 to 2.1 era) and need the current idioms: path() instead of url(), the STORAGES setting, zoneinfo, psycopg 3, POST-only logout, async views, django.tasks, template partials and the built-in CSP

The Bookshelf scenario

Every example builds one small original site, Bookshelf, in the same domain as the Python FastAPI and NestJS sections, so that the three stacks can be compared page by page:

a public catalogue of books, authors and reviews with server-rendered pages, PostgreSQL full-text search and pagination
a custom user model with email login, sign-up, password reset and per-object permissions for editing reviews
staff curation in the admin
cover-image uploads
English and Spanish translations
a "new review" live feed over Server-Sent Events from an async view, with a Channels WebSocket variant
review-moderation emails sent through django.tasks, with a Celery variant
Redis caching
a versioned REST API built with Django REST framework, with a Django Ninja variant
a sitemap and an RSS feed
a Docker deployment with Gunicorn and Uvicorn

Figure 1. The Bookshelf site: clients, servers, the Django project and its backing services

The final project layout (a config/ settings package, apps/catalog, apps/accounts, apps/reviews, apps/api, templates/, static/ and pyproject.toml) is assembled on Project Structure & Apps.

Reading path

The pages are ordered so that each one builds on the previous ones. Read them in this order the first time, then use them as a reference:

Foundations: what Django is made of, a first project, the project layout, settings, and manage.py.
Models and the ORM: fields, relationships, inheritance, migrations, queries, aggregation, managers, constraints, transactions, query optimisation, database backends and fixtures.
HTTP: the request/response cycle, URLs, function-based, class-based and generic views, middleware, sessions and cookies, file uploads and non-HTML responses.
Templates and the front end: the template language, partials with htmx, custom tags and filters, static files.
Forms: forms, validation, rendering and widgets, model forms and formsets.
The admin: registering models, then customising the admin for staff curation.
Authentication, authorisation and security: logins, the custom user model, permissions, passwords, the security middleware and settings, and Content Security Policy.
Application services: caching, email, the tasks framework and Celery, signals, logging, internationalisation, localisation and time zones, pagination and system checks.
Contrib apps: content types, sites, sitemaps and feeds, flat pages, redirects, humanize and GeoDjango.
Async and real-time: async views and the async ORM, then Channels and WebSockets.
Web APIs: Django REST framework, Django Ninja and GraphQL.
Testing: Django’s test framework, then pytest, factories and browser tests.
Production: deployment, containers, and performance.
Beyond the basics: what changed since older tutorials and how to upgrade, reusable apps and third-party packages, and best practices.

Readers who already know Django from older books can start with What’s Changed & Upgrading and then jump to the topics they use. The cheat sheet at Django Cheat Sheet condenses the whole section onto one page for quick lookup.

mindmap root((Django)) Foundations Introduction and architecture Getting started Project structure and apps Settings Management commands Models and the ORM Models and relationships Migrations Queries and aggregation Managers and constraints Transactions and optimisation Backends and fixtures HTTP Request and response cycle URLs and views Middleware Sessions and uploads Streaming and files Templates Template language Partials and htmx Static files Forms Validation and widgets Model forms and formsets Admin Admin site Customisation Auth and security Authentication Custom user model Permissions and passwords Security and CSP Application services Caching and email Tasks and Celery Signals and logging i18n and time zones Pagination and checks Contrib apps Content types Sitemaps and feeds GeoDjango Async and real time Async views and ORM Channels and WebSockets Web APIs Django REST framework Django Ninja GraphQL Testing Test framework pytest and browser tests Production Deployment Docker and Kubernetes Performance Beyond the basics Upgrading Reusable apps Best practices

Figure 2. The section at a glance

What’s covered

Each page builds on the Bookshelf scenario and ends with the official sources it derives from.

Foundations

Models and the ORM

HTTP: URLs, views and the request cycle

Templates and the front end

Forms

The admin

Authentication, authorisation and security

Application services

Contrib apps

Async and real-time

Web APIs

Testing

Production

Beyond the basics

Where related material lives elsewhere on this site

The Django pages link to existing material instead of repeating it, and cover only what Django adds.

Topic Where it lives How the Django section relates

Topic	Where it lives	How the Django section relates
The Python language: classes, decorators and metaclasses, typing, asyncio, packaging, pytest	Python Reference, including Classes & Objects, Decorators & Metaclasses, Type Hints, Concurrency & Async, Virtual Environments & Packaging and Testing	Django pages link here instead of re-explaining classes, metaclasses, decorators, asyncio, packaging or pytest.
API-first Python with FastAPI	Python FastAPI, including Introduction & Architecture and Sub-applications, WSGI & GraphQL	The introduction’s comparison table presents FastAPI as the API-first Python alternative, and the Django Ninja page links it for Pydantic-based APIs.
CORS	CORS	The security and Django REST framework pages link here for the theory and show only `django-cors-headers`.
Front end: HTML and CSS, Bootstrap, JavaScript, React, Vue, Angular, accessibility, browser testing	HTML & CSS, Bootstrap, JavaScript Development, React, Vue, Angular, Accessibility and End-to-End Testing in Real Browsers	Linked from the templates, static-files, front-end and browser-testing pages, which cover only the Django side.
The same ideas in other stacks	ASP.NET, Vaadin, Spring Boot and Quarkus Reference	The introduction’s framework comparison presents these as the same idea in other stacks.
GraphQL theory and the N+1 problem	GraphQL, including Python: Getting Started and Performance & the N+1 Problem	The GraphQL with Django page links here for theory and covers only Strawberry-Django and Graphene-Django.
OAuth 2.0, OpenID Connect, social login, MFA and JWT	OAuth Reference, including OpenID Connect, Social Login & Federation, Authentication Methods, 2FA & Passwordless and JWT & JOSE	The authentication, custom-user and Django REST framework pages link here for protocol theory.
Architecture: layering, monolith or microservices, choosing a stack	Architecture, including Layering Backend & Frontend, Choosing Monolith or Microservices and Starting a New Project: Which Path and Which Technologies	The project-structure page links here; the "Backend framework" table of the last page has a Python / Django row.
Messaging, Docker, Kubernetes and cloud platforms	Messaging Reference, Docker, Kubernetes Reference and Cloud	The Celery, Docker & Kubernetes and deployment pages show only the Django-specific parts.
Databases: SQL, Redis, schema evolution, slow queries, pagination, pgvector	SQL Reference, Redis Reference, Schema Evolution, Diagnosing Slow Queries, Pagination Strategies and PostgreSQL with pgvector	The ORM, migrations, query-optimisation, pagination and caching pages cover only the Django side.

The Python language: classes, decorators and metaclasses, typing, asyncio, packaging, pytest

Python Reference, including Classes & Objects, Decorators & Metaclasses, Type Hints, Concurrency & Async, Virtual Environments & Packaging and Testing

Django pages link here instead of re-explaining classes, metaclasses, decorators, asyncio, packaging or pytest.

API-first Python with FastAPI

Python FastAPI, including Introduction & Architecture and Sub-applications, WSGI & GraphQL

The introduction’s comparison table presents FastAPI as the API-first Python alternative, and the Django Ninja page links it for Pydantic-based APIs.

CORS

The security and Django REST framework pages link here for the theory and show only django-cors-headers.

Front end: HTML and CSS, Bootstrap, JavaScript, React, Vue, Angular, accessibility, browser testing

HTML & CSS, Bootstrap, JavaScript Development, React, Vue, Angular, Accessibility and End-to-End Testing in Real Browsers

Linked from the templates, static-files, front-end and browser-testing pages, which cover only the Django side.

The same ideas in other stacks

ASP.NET, Vaadin, Spring Boot and Quarkus Reference

The introduction’s framework comparison presents these as the same idea in other stacks.

GraphQL theory and the N+1 problem

GraphQL, including Python: Getting Started and Performance & the N+1 Problem

The GraphQL with Django page links here for theory and covers only Strawberry-Django and Graphene-Django.

OAuth 2.0, OpenID Connect, social login, MFA and JWT

OAuth Reference, including OpenID Connect, Social Login & Federation, Authentication Methods, 2FA & Passwordless and JWT & JOSE

The authentication, custom-user and Django REST framework pages link here for protocol theory.

Architecture: layering, monolith or microservices, choosing a stack

Architecture, including Layering Backend & Frontend, Choosing Monolith or Microservices and Starting a New Project: Which Path and Which Technologies

The project-structure page links here; the "Backend framework" table of the last page has a Python / Django row.

Messaging, Docker, Kubernetes and cloud platforms

Messaging Reference, Docker, Kubernetes Reference and Cloud

The Celery, Docker & Kubernetes and deployment pages show only the Django-specific parts.

Databases: SQL, Redis, schema evolution, slow queries, pagination, pgvector

SQL Reference, Redis Reference, Schema Evolution, Diagnosing Slow Queries, Pagination Strategies and PostgreSQL with pgvector

The ORM, migrations, query-optimisation, pagination and caching pages cover only the Django side.

Related topics that are planned but not yet part of this site are mentioned in prose only, where relevant: other Python web frameworks such as Flask, Tornado and Pyramid (issue #242), a programming languages comparison (#196), a cloud providers comparison (#201), and API managers, secret managers, gateways and scaling (#184). Thymeleaf templating is covered in the Thymeleaf section.

Bibliography

Every source used to prepare this section is listed here, each linked to its official site. Individual pages list the subset they derive from under their own == References heading.

Books

All four books target Django 1.11 to 2.1 (2017 to 2018), releases that have long been out of support. They were consulted for concept coverage, narrative and structure only; no text, code listing, figure or sample project is taken from them, every example in this section is written against the current official documentation, and the pages point out where the books are outdated.

Melé, A. Django 2 by Example: Build powerful and reliable Python web applications from scratch. Packt Publishing, 2018. ISBN 978-1-78847-248-7. Packt publisher page; companion code: PacktPublishing/Django-2-by-Example on GitHub. Current edition: Melé, A. Django 5 By Example, 5th ed. Packt Publishing, 2024. Packt publisher page.
Greenfeld, D. R. and Greenfeld, A. R. Two Scoops of Django 1.11: Best Practices for Django, 4th ed. Two Scoops Press, 2017. Feldroy (publisher) page, which also presents the current edition, Two Scoops of Django 3.x; companion code: twoscoops/two-scoops-of-django-1.11 on GitHub.
Marani, F. Practical Django 2 and Channels 2: Building Projects and Applications with Real-Time Capabilities. Apress, 2019. ISBN 978-1-4842-4098-4 (print), 978-1-4842-4099-1 (eBook). Apress / Springer publisher page; companion code: Apress/practical-django2-and-channels2 on GitHub.
Vincent, W. S. Django for Beginners: Build websites with Python & Django. Self-published, 2018. LearnDjango (author) page, which presents the current edition; companion code: wsvincent/djangoforbeginners on GitHub.

Official Django documentation

Published at docs.djangoproject.com (the full contents), grouped as the documentation is:

Getting started: the overview, installation, the eight-part tutorial, reusable apps and what to read next
Using Django: the topic guides (models and databases, HTTP, forms, templates, class-based views, migrations, files, testing, authentication, caching, conditional view processing, signing, email, internationalisation and localisation, logging, pagination, security, performance, serialisation, settings, signals, system checks, async support and tasks)
How-to guides: authentication backends, custom model fields, custom lookups, custom management commands, custom template tags and filters, custom storage, CSP, CSV and PDF output, deployment (WSGI and ASGI servers, static files, the deployment checklist), error reporting, initial data, legacy databases, logging, overriding templates, upgrading and writing migrations
API reference: applications, checks, class-based views, clickjacking protection, CSP, CSRF, databases, django-admin, exceptions, files, forms, logging, middleware, migration operations, models, paginator, request and response objects, schema editor, settings, signals, templates, tasks, unicode, URL dispatcher, utilities, validators and views
contrib packages: the admin, auth, contenttypes, flatpages, humanize, messages, PostgreSQL, redirects, sitemaps, sites, staticfiles and syndication, and GeoDjango
Release notes (from Django 1.11 to 6.1 and 6.1.2) and the deprecation timeline
Django’s release process and Django’s security policies
Design philosophies and API stability
FAQ
Django 5.2 release notes in the 5.2 LTS documentation

The Django project

Download and supported versions
The Django weblog (release and security announcements)
Django’s ecosystem (the community’s list of third-party packages)
Django trademark policy and the Django Software Foundation
The Django source code, including the built-in task backends and django/utils/deprecation.py
Django Enhancement Proposals (DEPs), including DEP 20 on calendar versioning
Django on PyPI

Python, packaging and the gateway interfaces

The books are consulted references for concept coverage, narrative and structure; they are not reproduced here. The official documentation linked above is authoritative, and where the two differ, the documentation of the version you run prevails.