Getting Started with Django

This chapter walks you from an empty folder to a running Django site: create a Python virtual environment, install Django, start a project, run the development server, and add your first app. It ends with a few tips for setting up your editor.

Prerequisites: Python and a virtual environment

Django is a Python package, so you need Python installed first. Each Django release supports a specific range of Python versions; check the installation notes in the official docs for the versions the current release requires.

Give every project its own virtual environment. A virtual environment is an isolated Python installation inside your project folder, so packages from one project never collide with another project or with the system Python.

mkdir mysite-project
cd mysite-project

# Create the virtual environment
python -m venv .venv

# Activate it on macOS or Linux
source .venv/bin/activate

# Activate it on Windows (PowerShell)
.venv\Scripts\Activate.ps1

Once activated, your prompt shows (.venv), and every python and pip you run comes from the environment. Run deactivate when you are done.

Installing Django

With the environment active, install Django with pip. Recording your dependencies in requirements.txt lets teammates and servers recreate the same environment later.

python -m pip install Django

# Check the installed version
python -m django --version

# Save the dependency list
python -m pip freeze > requirements.txt

pip freeze writes every installed package with its exact version. You can also maintain requirements.txt by hand. Many teams now use tools such as uv or Poetry to manage dependencies, but the overall workflow is the same.

Creating a project

In Django, a project is the whole site: its settings and URL configuration. An app is a Python package that provides one feature, such as a blog or a poll. Create the project with django-admin startproject.

# Create the mysite project in the current folder (.)
django-admin startproject mysite .

# Create the tables used by the built-in apps (admin, auth, ...)
python manage.py migrate

# Start the development server
python manage.py runserver

The trailing . puts manage.py in the current folder, with the mysite/ settings package next to it. Open http://127.0.0.1:8000/ and you will see the Django welcome page. To use another port, pass it along, as in python manage.py runserver 8080.

The development server reloads automatically when your code changes, but it is not meant for production. It has not gone through security or performance audits, so deployments use a server such as Gunicorn or Uvicorn instead (chapter 6).

Creating your first app

Features are organized into apps. Create one with startapp and register it in INSTALLED_APPS.

python manage.py startapp polls

# mysite/settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "polls",
]

Now write a simple view and hook it up to a URL.

# polls/views.py
from django.http import HttpResponse


def index(request):
    return HttpResponse("Welcome to the polls app.")

# polls/urls.py (new file)
from django.urls import path

from . import views

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

# mysite/urls.py
from django.contrib import admin
from django.urls import include, path

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

Visit http://127.0.0.1:8000/polls/ to see your message. include() mounts the app's URL list under a prefix in the project's URLconf.

Creating an admin user

Django ships with an admin site. Create a superuser and log in at /admin/.

python manage.py createsuperuser

Setting up your editor

In VS Code, install Microsoft's Python extension and choose the interpreter inside .venv with "Python: Select Interpreter" from the command palette. PyCharm Professional understands Django projects and can jump between views, templates and URLs. For formatting, Ruff or Black are common choices for Python code, and djLint is popular for templates.

Summary

• Create a virtual environment per project with python -m venv and install Django inside it.
• Use django-admin startproject for the project and python manage.py startapp for each app.
• Register new apps in INSTALLED_APPS and connect their URLs with include().
• runserver is for development only; production uses a dedicated WSGI or ASGI server.