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:
mkdir -p ~/bookmarks
cd ~/bookmarks
uv init --no-package
rm main.py
uv add "django>=6.1,<6.2"
uv run django-admin --versionuv 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:
uv run django-admin startproject config .
lsCheck 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:
uv run python manage.py migrateStart the development server. It stays in the foreground, so use a second terminal for the commands that follow:
uv run python manage.py runserverThe 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:
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:
uv run python manage.py startapp links
ls linksDjango 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:
cat >> config/settings.py <<'PY'
INSTALLED_APPS += ["links"]
PYNow describe the data. A model is a Python class, and each attribute is a column. Replace links/models.py:
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
PYURLField 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:
uv run python manage.py makemigrations links
uv run python manage.py migrateCheck 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:
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"]
PYCreate 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:
uv run python manage.py createsuperuserThen 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:
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:
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})
PYLink.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:
cat > links/urls.py <<'PY'
from django.urls import path
from . import views
app_name = "links"
urlpatterns = [
path("", views.index, name="index"),
]
PYThen connect it to the project's URLs in config/urls.py. This replaces the generated file, which contains only the admin route:
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")),
]
PYThe 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:
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>
HTMLAdd two bookmarks from the shell. The second has HTML in its title, to see what the template does with it:
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/')
"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/"><b>bold</b> attempt</a> and the second links to the Django documentation. The angle brackets of the second title appear as < and >. 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:
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 testDjango 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 = Trueshows detailed error pages with code and settings. It must beFalsein production.SECRET_KEYwas 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_HOSTSis empty, which only works whileDEBUGis on. List your real domain names.
Stop the server before you finish. Press Ctrl+C in its terminal.
Remove the demo project:
cd ~
rm -rf ~/bookmarksNext steps
- Serve it properly on a server: deploy a Django app with Gunicorn and Nginx.
- Learn the testing tool most Python teams use for the rest of their code: test Python code with pytest.
- The Django documentation at docs.djangoproject.com has a longer tutorial and the full reference for models, forms and the admin.
Related tutorials
- How to Use Virtual Environments and Install Packages in PythonYou will create an isolated Python 3.15 environment for a project, install a package into it with pip, record the exact versions, rebuild the environment from that record, and then manage the same project with uv.
- How to Write and Run Tests in Python with pytestYou will install pytest 9.2 in a uv project, write tests for a small price-parsing module, run many cases from one test with parametrize, read a failure and fix the code, and use a fixture that gives each test its own temporary folder.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials