Django is a full‑stack Python web framework used by large sites and small teams alike. It gives you an admin panel, an ORM, URL routing, templates, and security features out of the box. This guide gets you from zero to a running project and a first app, with clear explanations of how the pieces fit together. You should already be comfortable with Python basics, functions, and perhaps dictionaries and JSON.

1. What is Django and when to use it

Django is a high‑level framework: it assumes you want to build a website with a database, URLs, and HTML pages. It provides models (database tables), views (request handlers), templates (HTML with variables), and a built‑in admin so you can manage data without writing custom forms. It is a good fit for content sites, dashboards, internal tools, and APIs. If you need a minimal API only, FastAPI or Flask might be lighter; for a full web app with forms and auth, Django is hard to beat.

Django uses the Model‑View‑Template (MVT) pattern. “Model” is your data layer (database schema and queries). “View” is the logic that runs when a URL is requested (what data to load, what to return). “Template” is the HTML (or other output) that gets rendered. The framework handles the wiring between URLs, views, and templates.

2. Install Python and create a virtual environment

Use Python 3.8 or newer. Create and activate a virtual environment so your Django version is isolated from other projects:

python -m venv .venv

# Windows (Command Prompt or PowerShell):
.venv\Scripts\activate

# macOS / Linux:
source .venv/bin/activate

Your prompt should show (.venv). If you see errors about scripts being disabled on Windows, see PermissionError and your system execution policy.

3. Install Django

With the virtual environment active:

pip install django

# Confirm it worked:
django-admin --version

You should see a version like 5.0 or 4.2. If django-admin is not found, ensure the venv is activated and that pip installed into it (use pip show django to check).

4. Create your first project

A “project” is the top‑level container: settings, root URL config, and WSGI entry point. One project can contain many “apps” (features). Create a project named myproject:

django-admin startproject myproject
cd myproject

You now have a folder myproject with another folder inside it, also named myproject, plus manage.py. Do not confuse the outer folder (your project root) with the inner one (the Python package that holds settings and URLs).

5. Understand the project structure

myproject/
    manage.py           # CLI: runserver, migrate, shell, etc.
    myproject/
        __init__.py
        settings.py     # Database, apps, middleware, security
        urls.py         # Root URL routing
        asgi.py         # ASGI entry (async)
        wsgi.py         # WSGI entry (e.g. for production servers)

manage.py is the script you run for almost every Django command. settings.py is where you configure the database, installed apps, time zone, and static files. urls.py is the root URLconf: it maps URL patterns to views (or includes other URL modules from your apps).

6. Run the development server

From the project root (where manage.py lives):

python manage.py runserver

Django starts a local server at http://127.0.0.1:8000/. Open that URL in your browser; you should see the Django “install worked” page. To stop the server, press Ctrl+C in the terminal. Do not use this server in production; it is single‑threaded and not hardened for the internet. For production you would use something like Gunicorn behind Nginx, as covered in Django’s deployment docs.

7. Create an app

In Django, an “app” is a module that handles a slice of functionality (e.g. blog posts, user profiles, products). A project is a collection of apps. Create an app named myapp:

python manage.py startapp myapp

This creates a myapp folder with models.py, views.py, admin.py, apps.py, and migrations/. You must register the app in settings.py so Django loads it. Open myproject/settings.py, find INSTALLED_APPS, and add your app:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "myapp",   # add this line
]

8. Add a simple view and URL

To see something from your app, define a view and wire it to a URL. In myapp/views.py:

from django.http import HttpResponse

def index(request):
    return HttpResponse("Hello from myapp.")

Create myapp/urls.py (this file does not exist by default):

from django.urls import path
from . import views

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

Include it in the root URLconf. In myproject/urls.py, add an include so that paths under myapp/ are handled by the app:

from django.contrib import admin
from django.urls import path, include

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

Restart the dev server if it is running, then open http://127.0.0.1:8000/myapp/. You should see “Hello from myapp.” This confirms that the request hit your view through the URL routing. For more on views and templates, see Django views and the official tutorial.

9. Key concepts in one place

  • Project – The whole site: settings, root URLs, and one or more apps.
  • App – A feature module with its own models, views, templates, and URLs.
  • Model – Python class in models.py that defines database tables and fields. See Django Models.
  • View – Function (or class) in views.py that receives a request and returns a response (HTML, JSON, redirect).
  • Template – HTML file with Django template tags and variables, usually under app/templates/.
  • URLconf – urls.py in the project and in each app: maps URL patterns to views.

10. Common beginner issues

If you get ModuleNotFoundError for your app, check that the app is in INSTALLED_APPS and that you are running commands from the directory that contains manage.py. If you change models.py, run python manage.py makemigrations and then python manage.py migrate before expecting new tables. For “disallowed host” or static file issues, check settings.py (ALLOWED_HOSTS, STATIC_URL, and deployment docs).

11. Next steps

Define your first database tables in Django Models, then add forms and the Django admin to manage data. Use the official Django tutorial and our SQLite and JSON guides when you need to work with data files. For more Python web options, see Frameworks and Flask or FastAPI.