Skip to main content

Web frameworks · Beginner · 22 min

How to Create Your First Django 6 App

By Padding · Updated 15 Nov 2026
Django 6.1 · Python 3.15

You will create a Django 6.1 project with uv on Python 3.15, build a small bookmarks app with a database model, an admin screen, a page and a test, and see how the pieces connect.

On this page

Django is a Python web framework that includes what most sites need: a database layer, an admin interface, forms, authentication, URL routing and templates. You describe your data in Python, and Django builds the tables, the admin screens and the safe handling of user input.

In this tutorial you build a small bookmarks site. It has a model for saved links, an admin to add them, a public page that lists them and a test. You will touch every layer once, and you will see where each piece lives. It uses uv for the project and environment, as in the Python series: if you have not set it up, start with the Python install tutorial.

Step 1 · Create the project

Make a folder, start a uv project in it, and add Django. The version range stays in the 6.1 series:

Bash
mkdir -p ~/bookmarks
cd ~/bookmarks
uv init --no-package
rm main.py
uv add "django>=6.1,<6.2"
uv run django-admin --version

uv run runs a command inside the project's environment, creating it first if needed. Now create the Django project in the current folder. The trailing dot matters. Without it, Django makes an extra nested folder. The name config is a convention for the folder that holds project-wide settings:

Bash
uv run django-admin startproject config .
ls

Check it worked

django-admin --version prints 6.1. and a patch number. ls shows manage.py, config, pyproject.toml, uv.lock and README.md. manage.py is the command you use for everything else, and config/settings.py holds the project's settings.

Step 2 · Run the development server

Django keeps its own bookkeeping, such as users and sessions, in a database, so create the database tables first. The default database is a single SQLite file, db.sqlite3:

Bash
uv run python manage.py migrate

Start the development server. It stays in the foreground, so use a second terminal for the commands that follow:

Bash
uv run python manage.py runserver

The terminal that runs the server prints Starting development server at http://127.0.0.1:8000/ and Quit the server with CONTROL-C. Request the page:

Bash
curl -s http://127.0.0.1:8000/ | grep -o '<title>[^<]*</title>'

Check it worked

The output is <title>The install worked successfully! Congratulations!</title>. Open http://127.0.0.1:8000/ in a browser to see Django's welcome page with a rocket. The server reloads itself when you save a Python file, so you rarely need to restart it. Leave it running for the next steps. It is for development only: it is neither fast nor secure enough for the internet.

Step 3 · Create an app and a model

A Django project is made of apps, each with one job. Create one for bookmarks:

Bash
uv run python manage.py startapp links
ls links

Django has to be told that the app exists. Add it to INSTALLED_APPS by appending a line to the end of the settings file, which is safe to do however Django generates the rest:

Bash
cat >> config/settings.py <<'PY'

INSTALLED_APPS += ["links"]
PY

Now describe the data. A model is a Python class, and each attribute is a column. Replace links/models.py:

Bash
cat > links/models.py <<'PY'
from django.db import models


class Link(models.Model):
    title = models.CharField(max_length=120)
    url = models.URLField()
    created = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ["-created", "-id"]

    def __str__(self):
        return self.title
PY

URLField is a text column that checks for a valid web address in forms and in the admin. auto_now_add fills created when the row is first saved. ordering makes newest links come first by default, and __str__ decides how a link is named in the admin. Django turns model changes into migrations, which are small files that change the database step by step. Create the migration and apply it:

Bash
uv run python manage.py makemigrations links
uv run python manage.py migrate

Check it worked

makemigrations prints Migrations for 'links': and a line naming links/migrations/0001_initial.py with + Create model Link. migrate prints Applying links.0001_initial... OK. Commit the migration file with your code, because it records how the table is built.

Troubleshooting

ModuleNotFoundError: No module named 'links' means the app folder is missing or you ran the command outside the project folder. If makemigrations says No changes detected, check that the INSTALLED_APPS += ["links"] line is in config/settings.py and that links/models.py was saved.

Step 4 · Add the admin

Django's admin gives you screens to create, edit and delete rows. Register the model in links/admin.py:

Bash
cat > links/admin.py <<'PY'
from django.contrib import admin

from .models import Link


@admin.register(Link)
class LinkAdmin(admin.ModelAdmin):
    list_display = ["title", "url", "created"]
    search_fields = ["title", "url"]
PY

Create an administrator account. The command asks for a username, an email address and a password. The password does not show as you type it, and Django checks that it is not too weak:

Bash
uv run python manage.py createsuperuser

Then open http://127.0.0.1:8000/admin/ in your browser, log in, and use Add next to Links to save a bookmark. The admin form checks the address for you.

Check it worked

Check that the login page responds, and that the link table is empty and ready. The page is served by the dev server that is still running:

Bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/admin/login/
uv run python manage.py shell -c "from links.models import Link; print(Link.objects.count())"

The first command prints 200, and the second prints 0, unless you already added a link in the browser.

Step 5 · Show the links on a page

Three things connect a URL to a page: a URL pattern, a view and a template. Start with the view, a function that gets a request and returns a response. Replace links/views.py:

Bash
cat > links/views.py <<'PY'
from django.shortcuts import render

from .models import Link


def index(request):
    links = Link.objects.all()
    return render(request, "links/index.html", {"links": links})
PY

Link.objects.all() asks the database for every row, in the order the model sets. Next, give the app its own URL list in a new file, links/urls.py:

Bash
cat > links/urls.py <<'PY'
from django.urls import path

from . import views

app_name = "links"

urlpatterns = [
    path("", views.index, name="index"),
]
PY

Then connect it to the project's URLs in config/urls.py. This replaces the generated file, which contains only the admin route:

Bash
cat > config/urls.py <<'PY'
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("links.urls")),
]
PY

The template is an HTML file with slots for values. It goes in links/templates/links/. The repeated folder name is on purpose, because Django merges the template folders of all apps into one namespace and the inner folder keeps your names from clashing:

Bash
mkdir -p links/templates/links
cat > links/templates/links/index.html <<'HTML'
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Bookmarks</title>
</head>
<body>
  <h1>Bookmarks</h1>
  <ul>
    {% for link in links %}
      <li><a href="{{ link.url }}">{{ link.title }}</a></li>
    {% empty %}
      <li>No bookmarks yet.</li>
    {% endfor %}
  </ul>
</body>
</html>
HTML

Add two bookmarks from the shell. The second has HTML in its title, to see what the template does with it:

Bash
uv run python manage.py shell -c "
from links.models import Link
Link.objects.create(title='Django documentation', url='https://docs.djangoproject.com/')
Link.objects.create(title='<b>bold</b> attempt', url='https://example.com/')
"
Bash
curl -s http://127.0.0.1:8000/

Check it worked

The response is the page with two list items, newest first. The first reads <a href="https://example.com/">&lt;b&gt;bold&lt;/b&gt; attempt</a> and the second links to the Django documentation. The angle brackets of the second title appear as &lt; and &gt;. Django templates escape every variable by default, which protects you from injected markup and scripts, and you have to ask explicitly to switch that off. Refresh the page in a browser after adding a bookmark in the admin, and it appears with no restart.

Step 6 · Write a test

Django ships with a test runner and a test client that calls your views without a network. Replace links/tests.py:

Bash
cat > links/tests.py <<'PY'
from django.test import TestCase
from django.urls import reverse

from .models import Link


class IndexViewTests(TestCase):
    def test_empty_page(self):
        response = self.client.get(reverse("links:index"))
        self.assertEqual(response.status_code, 200)
        self.assertContains(response, "No bookmarks yet.")

    def test_newest_link_comes_first(self):
        Link.objects.create(title="Older", url="https://example.com/older")
        Link.objects.create(title="Newer", url="https://example.com/newer")
        response = self.client.get(reverse("links:index"))
        titles = [link.title for link in response.context["links"]]
        self.assertEqual(titles, ["Newer", "Older"])

    def test_titles_are_escaped(self):
        Link.objects.create(title="<script>alert(1)</script>", url="https://example.com/")
        response = self.client.get(reverse("links:index"))
        self.assertNotContains(response, "<script>alert(1)</script>")
PY
uv run python manage.py test

Django creates a temporary empty database for the run, so your real bookmarks are not touched.

Check it worked

The runner prints Found 3 test(s)., then Creating test database for alias 'default'..., a line of three dots, Ran 3 tests and OK.

Step 7 · Know what is not ready for production

The project works, but its settings are for development. Before it goes on a server, three things in config/settings.py change:

  • DEBUG = True shows detailed error pages with code and settings. It must be False in production.
  • SECRET_KEY was generated for you and sits in the file. It signs sessions and tokens, and anyone who has it can forge them. In production, load it from the environment or a file, and do not commit the real one.
  • ALLOWED_HOSTS is empty, which only works while DEBUG is on. List your real domain names.

Stop the server before you finish. Press Ctrl+C in its terminal.

Remove the demo project:

Bash
cd ~
rm -rf ~/bookmarks

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.