Django: A Beginner’s Guide to Python Web Development

Django is a Python framework for building web applications. It connects URLs to Python functions and includes tools for databases, forms, authentication, and administration. This notebook starts smaller: one URL, one response, and one automated test. You do not need a database model or an HTML template to understand that first request.

Use Python 3.11 and the Django 5.2 LTS series for this walkthrough. The code examples below were checked in a fresh project: first a failing test, then the completed page. This is a learning exercise, not a production deployment recipe.

1. Create an isolated environment

Create a new, empty working folder. A virtual environment keeps this project’s packages separate from other Python projects. On Windows Command Prompt, with Python 3.11 installed and available through the Python launcher:

mkdir django-notebook
cd django-notebook
py -3.11 -m venv .venv
.venv\Scripts\activate.bat

On macOS or Linux, with Python 3.11 installed:

mkdir django-notebook
cd django-notebook
python3.11 -m venv .venv
source .venv/bin/activate

The automated Windows run uses uv venv --python 3.11 --seed .venv instead of the launcher. It invokes the environment’s executable directly; activation is simply a convenience for finding that executable. The macOS/Linux commands are provided for those platforms, not claimed as executed here.

After activation, check the interpreter and install Django. Quoting the version constraint prevents the shell from interpreting its comparison characters. The range stays within the 5.2 series while allowing patch updates.

python --version
python -m pip install "Django>=5.2,<5.3"
python -m django --version

2. Generate the project and app

Run these commands inside your working folder:

python -m django startproject config .
python manage.py startapp pages

python -m django runs Django’s command-line utility through the selected Python interpreter, avoiding a separate django-admin PATH dependency. The final dot puts manage.py in the current folder. config holds project settings and root URL configuration; pages holds this small feature.

3. Write a test before the page

Replace the generated contents of pages/tests.py with:

from django.test import SimpleTestCase


class HomePageTests(SimpleTestCase):
    def test_home_returns_greeting(self):
        response = self.client.get("/")
        self.assertContains(response, "Hello, Django!", status_code=200)

Run the test explicitly by its module name:

python manage.py test pages.tests

This is the RED step: it must fail because the greeting does not exist yet. Check the failure rather than assuming every error is useful. A syntax error or missing Django installation is not the expected missing-page failure. SimpleTestCase is enough because this page does not query a database; assertContains checks both the status and response text.

4. Add the view and connect its URL

Replace pages/views.py with a named view:

from django.http import HttpResponse


def home(request):
    return HttpResponse("Hello, Django!")

Replace config/urls.py with:

from django.contrib import admin
from django.urls import path
from pages.views import home

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", home, name="home"),
]

The empty route matches the site root. Django calls pages.views.home with the request and sends its HttpResponse back. There is no leading slash in a path() pattern. This import-only example does not require adding pages to INSTALLED_APPS; register it when you introduce models or app-discovered resources. The explicit test module keeps this example’s test discoverable.

5. Get GREEN, migrate, and browse

python manage.py test pages.tests
python manage.py migrate
python manage.py check
python manage.py runserver 127.0.0.1:8000

The test should now pass: this is GREEN. Migrations initialize the default SQLite database for Django’s built-in apps, even though our greeting needs no database. Open http://127.0.0.1:8000/ and expect Hello, Django!. Stop the server with Ctrl+C. Runserver is development-only. Do not expose it as your public production server; deployment needs separate security and hosting configuration.

What was actually verified

A fresh Windows scratch project ran with Python 3.11.15 and Django 5.2.18. Before the view and route existed, the test failed with 404 != 200. After adding them, one test passed, migrations completed, and the system check reported no issues. A real local development-server request returned HTTP 200 with Hello, Django!. The verification script uses an available port and disables reloading so it can stop its server cleanly.

Common pitfalls and next steps

If Django cannot be imported, check python --version and the active environment before reinstalling anything. If manage.py cannot be found, change into the folder containing it. A 404 suggests a missing or mismatched route. An occupied port can be avoided with python manage.py runserver 127.0.0.1:8001. Keep generated secrets and local database files out of public repositories.

Continue with the official installation guide, first Django tutorial, testing tools, and deployment checklist. Add a template next, then a model when the page actually needs stored data.

About the author: Ahmad Faraz and Code & Craft.