Getting Started

Each Django release supports a window of Python versions, and only the latest micro release of each Python series is officially supported:

Source: FAQ: Installation, Django 6.1 release notes

The practical rule is that Django 6.0 and later need Python 3.12 or newer, so an old system Python cannot install them. This is easy to trip over: with the Python 3.9 that ships with some operating systems, pip looks at the package index, sees that none of the newer releases declares support for its interpreter and fails with a message that looks like a typo in the package name:

Source: FAQ: Installation

The list of versions in that error stops at 4.2.30, which is the newest release whose metadata accepts Python 3.9 (the output above was captured on 2026-10-03). The fix is a newer interpreter, not a different command. If you must stay on an older Python for a while, pin the Django series it supports (Django 4.2 for Python 3.9) and read the matching documentation version through the version switcher on docs.djangoproject.com. The FAQ also gives the rule behind the table: Django supports a Python version up to and including the first LTS release whose security support ends after that Python version’s own security support ends. Python 3.10 and 3.11 were last supported by the Django 5.2.x series.

Give every project its own virtual environment, so its packages never collide with another project’s or with the system. The tool-agnostic mechanics (what a virtual environment is, requirements.txt, lock files) are covered in the Python Reference, in Virtual Environments & Packaging, and are not repeated here. Two routes work equally well.

With uv, a fast project manager that creates the environment, installs Django and records exact versions in uv.lock:

Source: Quick install guide

uv init --bare writes only a pyproject.toml. uv add creates .venv (you never activate it), adds the dependency to pyproject.toml and locks the resolved versions. This was run on 2026-10-03 and installed asgiref==3.12.1, django==6.1.1 and sqlparse==0.6.0; uv run python -m django --version printed 6.1.1. Prefix every later command with uv run (for example uv run python manage.py runserver) or activate .venv yourself.

With the standard library and pip:

Source: How to install Django

Quote the requirement: without quotes the shell treats > and < as redirections. Pinning the series (>=6.1,<6.2) means you receive security and bug-fix releases (6.1.2 and later) without a surprise jump to the next feature release. After the install, django-admin is on the path of the environment, and python -m django is an equivalent spelling that always uses the interpreter you are running, which is handy when two environments are installed.

Verify from Python itself, as the installation guide does:

Source: Quick install guide

Django ships with a development server and uses SQLite, which is part of Python, so nothing else has to be installed for this page. For production the installation guide recommends PostgreSQL (officially supported: PostgreSQL, MariaDB, MySQL, Oracle and SQLite). Django 6.1 requires PostgreSQL 15 or newer, MySQL 8.4 or newer, MariaDB 10.11 or newer and SQLite 3.37 or newer, and a PostgreSQL project installs psycopg (psycopg 3 has been supported since Django 4.2). Production servers (Gunicorn, Uvicorn, Daphne, Granian) are the subject of the deployment pages; nothing on this page needs them. Windows users can follow the official How to install Django on Windows for the interpreter and path setup.

Source: How to install Django, Databases

Source: Writing your first Django app, part 1

Source: Writing your first Django app, part 1

Two things in the generated settings.py of Django 6.1.1 are worth knowing before you edit it. First, the file contains no DEFAULT_AUTO_FIELD: that setting was written into generated projects from Django 3.2, but since Django 6.0 it defaults to django.db.models.BigAutoField and the lines were removed from the project and app templates. Second, a MAILERS setting with the console email backend is generated (new in 6.1; it will replace EMAIL_BACKEND and the EMAIL_* settings in Django 2028, see the section on recent changes below):

Source: Django 6.1 release notes

SECRET_KEY is generated per project with the prefix django-insecure-. It is acceptable for local experiments and must be replaced before deployment; the deployment check below shows exactly how Django complains. Settings are covered in depth on the Settings & Configuration page of this section.

Source: django-admin runserver

The reloader watches Python files and restarts the process on change (it prints Watching for file changes with StatReloader). If Linux or macOS has both pywatchman and the Watchman service installed, Django switches to kernel notifications instead of polling file timestamps once per second; the environment variable DJANGO_WATCHMAN_TIMEOUT raises the default five-second client timeout. Adding a new file does not always trigger a restart, so restart by hand when a new module or template directory is not picked up. Each request and response is logged by the django.server logger, and the warning banner can be silenced with DJANGO_RUNSERVER_HIDE_WARNING=true.

Where the development server sits in the request cycle: it is a small multithreaded WSGI server. It builds a WSGI environ for each HTTP request and calls the object named by the WSGI_APPLICATION setting (mysite.wsgi.application), exactly like Gunicorn would, so everything described under "The request cycle" below runs identically. It has not been security audited and is not meant for production. For asynchronous code it still works: an async def view runs under it (Django adapts it to the synchronous request path), but only an ASGI server runs async views natively. This was checked with a view added to the polls app below: it returned {"questions": 1} under runserver and under python -m uvicorn mysite.asgi:application.

Add the app to INSTALLED_APPS in mysite/settings.py. The tutorial uses the dotted path of the configuration class:

Source: Writing your first Django app, part 2

Since Django 3.2 the shorter entry "polls" is equivalent when polls/apps.py defines a single AppConfig subclass (automatic AppConfig discovery); this was verified by running the whole project below with "polls" instead: check is clean and all ten tests pass. Books written for Django 1.x and 2.x register apps as "polls" and add default_app_config = "polls.apps.PollsConfig" to init.py; that variable was deprecated in 3.2 and removed in 4.1, so do not copy it.

A view is a callable that receives an HttpRequest and returns an HttpResponse or raises an exception such as Http404. That is the only contract.

To reach it, give the app a URLconf (a list named urlpatterns) and mount that in the project’s URLconf:

Source: Writing your first Django app, part 1

How it works: path(route, view, kwargs=None, name=None) registers one pattern; include() hands the rest of the URL to another URLconf after chopping off the part that already matched (polls/). So the app can be mounted under /polls/, /fun_polls/ or /content/polls/ without changing its own file. Always use include() for other URL patterns; the only exception is admin.site.urls, which is a ready-made URLconf. Patterns are tried in order and the first match wins. A test for this stage is three lines:

Source: Writing and running tests

(manage.py test ran this in a throw-away project: Ran 1 test …​ OK.)

INSTALLED_APPS lists the default apps (admin, auth, contenttypes, sessions, messages, staticfiles), several of which need tables, so apply their migrations first:

Source: Writing your first Django app, part 2

Then define the data. A model is a class that subclasses django.db.models.Model; every class attribute that is a Field becomes a column:

Source: Writing your first Django app, part 2

Source: Writing your first Django app, part 2

The rule to remember is the three-step loop for every model change: edit models.py, run makemigrations to write a migration file, run migrate to apply it. The two commands are separate because migration files are committed and shipped with the code, so production applies the same history as development. manage.py check validates the project without touching the database or creating migrations, and manage.py sqlmigrate polls 0001 prints the SQL a migration will run.

max_length on CharField is required and is used both for the database column and for validation. ForeignKey needs on_delete; CASCADE deletes the choices with their question. Django 6.1 adds database-level alternatives (DB_CASCADE, DB_SET_NULL, DB_SET_DEFAULT) that let the database delete rows without loading them into Python; they do not send the pre_delete and post_delete signals. No primary key is declared: Django adds an automatic id (BigAutoField by default since 6.0; since 3.2 it was controlled by DEFAULT_AUTO_FIELD). The @admin.display decorator on the method (since Django 3.2; it replaces the older short_description and boolean function attributes) configures how the admin shows it and is used in step 6.

Source: Writing your first Django app, part 2

shell runs a Python prompt with DJANGO_SETTINGS_MODULE set and Django initialised, which plain python does not. Since 5.2 the shell imports the models of all installed apps automatically, and since 6.0 it also imports common utilities; run it with -v 2 to see the list (on this project it imported 14 objects, including settings, connection, models, timezone, User, Group, Choice and Question):

Source: Writing your first Django app, part 2

Older tutorials start this session with from polls.models import Choice, Question; with Django 5.2 or newer that line is no longer needed. Use timezone.now() rather than datetime.datetime.now() for stored datetimes: time zone support is on by default (USE_TZ = True), so Django expects aware datetimes. choice_set is the reverse side of the ForeignKey, named after the model by default. save() must be called explicitly.

Part 3 replaces the stub views by ones that read the database and render HTML. The pieces are the <int:question_id> path converter (which captures a segment of the URL as an int and passes it to the view as a keyword argument), the render() shortcut, get_object_or_404(), a template, and namespaced URL names:

Source: Writing your first Django app, part 3

Notes that matter:

Source: Writing your first Django app, part 4

Three habits are taught by this one view and are worth memorising. State-changing forms use method="post" and carry {% csrf_token %}; a POST without the token is rejected. This was checked with curl:

Source: How to use Django’s CSRF protection

The vote is counted with F("votes") + 1, which makes the database perform the increment, so two simultaneous voters cannot overwrite each other’s update (a read-modify-write in Python would lose one). One caveat: after save() the Python object holds the F expression, not a number, so call refresh_from_db() before reading votes again in the same request. The view always answers a successful POST with a redirect (the Post/Redirect/Get pattern), so the Back button or a refresh does not resubmit the form. request.POST values are always strings, and request.POST["choice"] raises KeyError when the field is missing, which the view handles.

The detail, results and index views are the most common pattern of web development (fetch by key, render a template), so Django provides class-based generic views for them. The tutorial refactors to:

Source: Writing your first Django app, part 4

DetailView expects the URL keyword to be named pk (hence <int:pk>), derives the context variable name question from the model, and would default to the template polls/question_detail.html; template_name overrides that. ListView names its context variable question_list and defaults to polls/question_list.html, so the tutorial sets context_object_name and template_name. The timezone.now() filter is added in tutorial part 5 so that future-dated questions stay hidden. Class-based views are covered on their own page of this section.

Source: Writing your first Django app, part 5

Source: Writing your first Django app, part 5

Tests run against a separate, temporary database (an in-memory SQLite database here), so your real data is never touched, and TestCase wraps every test in a transaction that is rolled back. The built-in test client (self.client) makes requests without a network and exposes response.context and assertContains. The tutorial’s most important lesson is to write the failing test first for a bug (was_published_recently() returned True for questions dated in the future) and then fix the code. Note the method name assertQuerySetEqual: the old spelling assertQuerysetEqual was deprecated in Django 4.2 and removed in 5.1, so older tutorials fail with AttributeError on current versions. Testing is the subject of its own pages in this section.

Static files (CSS, JavaScript, images) live in static/ directories next to templates and are namespaced the same way: polls/static/polls/style.css. The {% load static %} tag and {% static %} generate the URL from STATIC_URL:

Source: Writing your first Django app, part 6

Under runserver with DEBUG = True, django.contrib.staticfiles serves them from the app directories (the curl check returned HTTP 200, Content-Type: text/css). In production there is no such magic: collectstatic gathers files into STATIC_ROOT and a web server or WhiteNoise serves them, which the Static & Media Files page covers. Old books write {% load staticfiles %} or {% load admin_static %}; those tag libraries were removed in Django 3.0, use {% load static %}.

Create an administrator and register the models:

Source: Writing your first Django app, part 2

createsuperuser prompts for a username, an optional email address and a password (twice); never script a real password into a command line or a repository. Then customise the admin as in part 7:

Source: Writing your first Django app, part 7

Visit /admin/, log in and you get create, change, delete and history screens for questions, with Choice rows edited inline on the question page (TabularInline is the compact layout, StackedInline the roomy one), a change list with the columns of list_display, a date filter and a search box. Two ModelAdmin facts help to read the code: list_display entries may be methods of the model (here with the @admin.display decorator from step 2), and fieldsets controls grouping, the collapse class hides a group behind a toggle. The admin is a page of its own in this section.

Part 8 installs django-debug-toolbar (version 8.0.0 on 2026-10-03, which declares support for Django 5.2, 6.0 and 6.1) as the model for every other ecosystem package: install with pip or uv, add the app, add the middleware, add the URL, set INTERNAL_IPS:

Source: Writing your first Django app, part 8

Each toolbar setup step above is described in the package’s own installation guide (linked from the tutorial); this was applied to a copy of the project and check stayed clean. A pitfall tied to the tutorial’s note that its templates are incomplete HTML: the toolbar injects its panel just before </body>, so on the tutorial’s fragment pages (/polls/1/) the toolbar was absent (0 matches for its markup), while on a full HTML page such as /admin/login/ it appeared. If the toolbar "does not show", check that the response is a complete HTML document, that DEBUG is on and that the request IP is in INTERNAL_IPS.