Установка, проект и первое приложение

Прежде чем писать код, нужно поставить Django правильно: в изолированном окружении и актуальной версии. Этот шаг новички часто делают небрежно — и потом ловят странные ошибки.

Суть: создаём виртуальное окружение, ставим Django через pip, генерируем каркас проекта командой django-admin startproject и запускаем встроенный сервер разработки.

Виртуальное окружение — это не опционально

Python ставит библиотеки в общую системную папку. Если один проект требует Django 5.2, а другой — Django 4.2, глобальная установка приведёт к конфликту: обновив пакет для одного, вы сломаете другой. Решение — виртуальное окружение: изолированная папка со своей копией Python и своими пакетами. Создаётся оно встроенным модулем venv.

python3 -m venv venv
source venv/bin/activate      # Linux / macOS
venv\Scripts\activate         # Windows
pip install --upgrade pip
pip install Django==5.2

После активации в начале строки терминала появится (venv). Это значит, что python и pip теперь указывают на изолированное окружение. Проверить версию можно так:

python -m django --version
# 5.2

Создаём проект

Команда django-admin startproject разворачивает каркас. Обратите внимание на точку в конце — она кладёт файлы в текущую папку, а не в лишний вложенный каталог:

django-admin startproject mysite .
python manage.py runserver

Откройте http://127.0.0.1:8000 — вы увидите страницу-ракету с поздравлением. Сервер разработки автоматически перезапускается при изменении кода, что очень удобно. Но запомните: этот сервер только для разработки, в продакшене используют Gunicorn или Uvicorn, о чём поговорим в последнем разделе.

Структура проекта

Разберём, что сгенерировалось:

mysite/
├── manage.py          ── утилита управления (runserver, migrate, ...)
├── db.sqlite3         ── появится после первой миграции
└── mysite/
    ├── __init__.py
    ├── settings.py    ── ВСЕ настройки проекта
    ├── urls.py        ── корневой URLconf
    ├── asgi.py        ── точка входа для ASGI-серверов
    └── wsgi.py        ── точка входа для WSGI-серверов

Файл manage.py — ваш главный инструмент: через него запускают сервер, применяют миграции, открывают shell. settings.py — мозг проекта: список приложений, база данных, язык, часовой пояс. urls.py — таблица маршрутов.

Создаём приложение

python manage.py startapp blog

Появится папка blog/ с файлами models.py, views.py, admin.py и другими. Чтобы Django узнал о приложении, его нужно зарегистрировать в settings.py:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",  # наше приложение
]

Как это работает под капотом

manage.py просто выставляет переменную окружения DJANGO_SETTINGS_MODULE и передаёт управление в django.core.management. Когда вы пишете python manage.py runserver, Django читает settings.py, импортирует все приложения из INSTALLED_APPS, строит реестр моделей и поднимает лёгкий WSGI-сервер. Каждое изменение файла отслеживается автоперезагрузчиком, который перезапускает процесс.

Регистрация приложений — это, по сути, фильтрация конфигов из списка словарей. Вот наглядная аналогия на чистом Python, как Django мог бы собирать активные приложения:

# Попробуй сам ▶ — упрощённая модель INSTALLED_APPS
installed = [
    {"name": "admin", "core": True},
    {"name": "auth", "core": True},
    {"name": "blog", "core": False},
    {"name": "shop", "core": False},
]

# отделяем наши приложения от встроенных
mine = [app["name"] for app in installed if not app["core"]]
core = [app["name"] for app in installed if app["core"]]

print("Встроенные Django:", core)
print("Мои приложения:   ", mine)
print("Всего приложений: ", len(installed))

Частые ошибки

Ставить Django глобально. Без venv проекты конфликтуют по версиям.
Забыть точку в startproject mysite . — получаете лишнюю вложенную папку.
Не добавить приложение в INSTALLED_APPS. Тогда его модели и шаблоны Django просто не увидит.
Коммитить venv и db.sqlite3 в git. Их место в .gitignore.

Best practices

Фиксируйте версии в requirements.txt командой pip freeze > requirements.txt.
Держите секреты (SECRET_KEY, пароли БД) в переменных окружения, а не в settings.py.
Называйте приложения коротко и по смыслу: blog, accounts, orders.

Итоги

Установка Django — это venv, pip install Django, startproject и startapp. Проект хранит настройки, приложения — логику. Зарегистрируйте приложение в INSTALLED_APPS, запустите runserver — и каркас готов. Дальше наполним его моделями.