🛠️ Setting Up a Django Project

Prerequisites

Setting up cleanly is like laying out your ingredients before you start cooking — it prevents mid-recipe scrambles. Confirm you have these ready:

The Virtual Environment

A virtual environment is an isolated, per-project Python installation. Packages you install inside it stay inside it, so Project A's Django 5.0 never collides with Project B's Django 4.2, and nothing pollutes your system Python.

🧰 Analogy: A virtual environment is a separate toolbox for each project. You never accidentally grab Project A's wrench while working on Project B, and each toolbox can hold a different version of the same tool without conflict.

Create and activate

# Windows (PowerShell)
python -m venv venv
venv\Scripts\activate

# macOS / Linux
python3 -m venv venv
source venv/bin/activate

When it's active, your prompt gains a (venv) prefix. Every pip install now lands in this isolated folder. When you're done for the day:

deactivate

Installing Django

With the environment active, install Django from PyPI:

# Latest stable release
pip install django

# Or pin a specific version (recommended for teams)
pip install "django==5.1.*"

Confirm it worked:

python -m django --version

5.1.4

Immediately record what you installed so a teammate (or future you) can rebuild the exact environment:

pip freeze > requirements.txt

Anyone can then reproduce it with pip install -r requirements.txt. Think of requirements.txt as the recipe card for your project's dependencies.

Creating the Project

Django ships a command-line tool, django-admin, that scaffolds a new project:

django-admin startproject myproject

That creates a myproject/ folder containing another myproject/ folder — a nesting that trips up beginners. To avoid the double folder, add a trailing dot to build the project in the current directory:

# Common in real projects — no extra wrapper folder
mkdir blogsite && cd blogsite
django-admin startproject config .

Here the inner package is named config, a popular convention that makes "the settings package" obvious. For the rest of this lesson we'll use the default myproject name to match what startproject myproject produces.

What you get

myproject/
├── manage.py
└── myproject/
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

🏗️ Analogy: startproject pours the foundation and frames the walls. The house is empty, but it is structurally complete and ready for you to move features in.

Understanding the Files

Every file has a job. Learn them once and the project layout stops feeling mysterious.

manage.py — the control panel

You will type python manage.py … hundreds of times. It's a thin wrapper that points Django at your settings and forwards commands:

#!/usr/bin/env python
"""Django's command-line utility for administrative tasks."""
import os
import sys


def main():
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH? Did you forget to activate "
            "a virtual environment?"
        ) from exc
    execute_from_command_line(sys.argv)


if __name__ == "__main__":
    main()

urls.py — the routing table

A fresh project routes only the admin site. You'll add your own patterns here (usually with include()) as you build apps:

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

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

💁 Analogy: urls.py is the receptionist. When a request walks in, the receptionist reads the requested path and directs it to the right department (view).

Configuring settings.py

The settings.py file is your project's control center. Here are the settings you'll touch most often.

Installed apps & middleware

Every project starts with Django's own apps enabled. You'll append your apps to this list later:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # Your apps go here, e.g.:
    # "blog",
]

Database

SQLite is the zero-config default — perfect for learning. For production you'll switch to PostgreSQL:

# Default: SQLite (development)
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

# Production: PostgreSQL
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "blogsite",
        "USER": "blog_user",
        "PASSWORD": os.environ["DB_PASSWORD"],
        "HOST": "localhost",
        "PORT": "5432",
    }
}

Templates, static files, and locale

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],  # project-level templates
        "APP_DIRS": True,                    # each app's templates/ folder
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

STATIC_URL = "static/"
STATICFILES_DIRS = [BASE_DIR / "static"]

TIME_ZONE = "America/New_York"
LANGUAGE_CODE = "en-us"
USE_TZ = True

Security: DEBUG, SECRET_KEY, ALLOWED_HOSTS

These three settings behave differently in development and production. The safest pattern is to read them from environment variables:

import os

# Never hard-code the real key or commit it — read from the environment.
SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "dev-only-insecure-key")

# True locally; MUST be False in production.
DEBUG = os.environ.get("DJANGO_DEBUG", "True") == "True"

ALLOWED_HOSTS = [] if DEBUG else ["example.com", "www.example.com"]

Running the Server

From the folder that contains manage.py, start Django's built-in development server:

python manage.py runserver

# Or on a different port
python manage.py runserver 8080

Visit http://127.0.0.1:8000/ and you'll meet Django's launch page:

The server auto-reloads when you save a file, so you rarely restart it manually.

Migrations & the Superuser

Django's built-in apps (auth, sessions, admin) need database tables. The migrate command creates them:

python manage.py migrate

Now create an administrator account so you can log into the admin site:

python manage.py createsuperuser

You'll be prompted for a username, email, and password. Then restart the server (if needed), visit http://127.0.0.1:8000/admin/, and log in. You get a full data-management interface for free.

Commands you'll use constantly

Hands-on Exercise

# 1. Environment
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

# 2. Install + record
pip install django
pip freeze > requirements.txt

# 3. Create the project
mkdir blogsite && cd blogsite
django-admin startproject config .

# 4. Edit config/settings.py -> TIME_ZONE = "America/New_York"

# 5. Database + admin user
python manage.py migrate
python manage.py createsuperuser

# 6. Run it
python manage.py runserver
# Open http://127.0.0.1:8000/admin/ and log in

Summary & Quiz

📚 Further Reading

• Django tutorial, part 1 — writing your first app
• Django settings reference
• Deployment checklist
• Python venv documentation

🚀 What's Next?

Your project is running, but it doesn't do anything yet. In the next lesson, Django Applications Structure, you'll create your first app and learn how projects and apps fit together.