Как создать приложение в Django: команда startapp

Чтобы создать приложение в Django, выполните в корне проекта python manage.py startapp blog, а затем добавьте 'blog' в список INSTALLED_APPS в settings.py. Без регистрации Django не увидит модели, шаблоны и миграции нового приложения.

python manage.py startapp blog

# config/settings.py
INSTALLED_APPS = [
    # ...встроенные приложения django.contrib...
    'blog',
]

Ниже разберём, чем приложение Django отличается от проекта, какие файлы создаёт startapp, как подключить к приложению URL, view и шаблоны и что делать с типичными ошибками. Примеры проверены на Django 6.1 и 5.2 LTS.

Проект и приложение в Django: в чём разница

Проект — это сайт целиком: настройки, корневые URL, подключение к базе данных. Он создаётся один раз командой startproject.

Приложение (app) — модуль с одной областью ответственности: блог, каталог товаров, личный кабинет, API. В нём живут модели, view, шаблоны и тесты этой части сайта. В одном проекте обычно несколько приложений, и одно приложение можно перенести в другой проект.

Встроенные возможности Django устроены так же: админка — это приложение django.contrib.admin, пользователи — django.contrib.auth. Их вы видите в INSTALLED_APPS сразу после создания проекта.

Проект	Приложение
django-admin startproject config .	python manage.py startapp blog
один на сайт	сколько угодно
settings.py, корневой urls.py, WSGI/ASGI	модели, view, шаблоны, админка, миграции
не переносится между сайтами	можно переиспользовать в других проектах

Как создать приложение командой startapp

Перейдите в папку, где лежит manage.py, и активируйте виртуальное окружение:

Windows:

cd mysite
.venv\Scripts\activate
python manage.py startapp blog

macOS и Linux:

cd mysite
source .venv/bin/activate
python manage.py startapp blog

Команда ничего не выводит при успехе — рядом с manage.py появится папка blog. Вместо python manage.py startapp можно вызвать django-admin startapp blog: результат тот же, но manage.py дополнительно подхватывает настройки проекта, поэтому внутри проекта принято использовать его.

Имя приложения должно быть корректным идентификатором Python: латиница, цифры и подчёркивание, без дефисов. Обычно его пишут во множественном или собирательном числе: blog, products, accounts, orders.

Структура приложения Django

blog/
├── __init__.py
├── admin.py
├── apps.py
├── migrations/
│   └── __init__.py
├── models.py
├── tests.py
└── views.py

Файл	Зачем нужен
models.py	Модели — классы, описывающие таблицы базы данных
views.py	Представления (view) — функции и классы, которые обрабатывают запросы
admin.py	Регистрация моделей в админке Django
apps.py	Конфигурация приложения (AppConfig): имя, подпись в админке, хуки запуска
migrations/	Файлы миграций, которые создаёт makemigrations
tests.py	Тесты приложения

Некоторых привычных файлов startapp не создаёт — их добавляют вручную по мере надобности:

• urls.py — маршруты приложения;
• templates/blog/ — HTML-шаблоны;
• static/blog/ — CSS, JavaScript и картинки;
• forms.py — формы.

Зарегистрируйте приложение в INSTALLED_APPS

# config/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'blog',
]

Можно указать и полный путь к конфигурации — 'blog.apps.BlogConfig'. Если в apps.py ровно один класс AppConfig, Django находит его сам, поэтому короткая запись 'blog' работает так же.

В apps.py удобно задать человекочитаемое название — оно появится в админке:

# blog/apps.py
from django.apps import AppConfig


class BlogConfig(AppConfig):
    name = 'blog'
    verbose_name = 'Блог'

Важно: в Django 5.2 startapp добавляет в BlogConfig строку default_auto_field = 'django.db.models.BigAutoField'. В Django 6.0+ её нет, потому что BigAutoField и так используется по умолчанию. Если строка есть — удалять её не нужно.

Первая view и маршруты приложения

Напишите простую view:

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


def index(request):
    return HttpResponse('Привет из приложения blog!')

Создайте в папке приложения файл urls.py:

# blog/urls.py
from django.urls import path

from . import views

app_name = 'blog'

urlpatterns = [
    path('', views.index, name='index'),
]

И подключите его в корневом urls.py проекта через include():

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

urlpatterns = [
    path('admin/', admin.site.urls),
    path('blog/', include('blog.urls')),
]

Запустите python manage.py runserver и откройте http://127.0.0.1:8000/blog/ — увидите текст из view. app_name задаёт пространство имён: ссылка на страницу строится как reverse('blog:index') в Python или {% url 'blog:index' %} в шаблоне.

Совет: после подключения своих маршрутов стартовая страница с ракетой на http://127.0.0.1:8000/ пропадёт и сменится ошибкой 404. Django показывает «ракету», только пока в проекте нет других URL, кроме админки; чтобы на главной что-то открывалось, добавьте маршрут с пустым путём.

Шаблоны приложения

При настройке 'APP_DIRS': True (она стоит по умолчанию) Django ищет шаблоны в папке templates каждого приложения из INSTALLED_APPS. Внутри принято создавать ещё одну папку с именем приложения, чтобы шаблоны разных приложений не конфликтовали:

blog/
└── templates/
    └── blog/
        └── about.html

<!-- blog/templates/blog/about.html -->
<h1>{{ title }}</h1>

# blog/views.py
from django.shortcuts import render


def about(request):
    return render(request, 'blog/about.html', {'title': 'О блоге'})

# blog/urls.py
urlpatterns = [
    path('', views.index, name='index'),
    path('about/', views.about, name='about'),
]

Модели, миграции и админка

Опишите модель:

# blog/models.py
from django.db import models


class Post(models.Model):
    title = models.CharField('Заголовок', max_length=200)
    text = models.TextField('Текст')
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title

Создайте и примените миграцию:

python manage.py makemigrations blog
python manage.py migrate

Migrations for 'blog':
  blog/migrations/0001_initial.py
    + Create model Post

Зарегистрируйте модель в админке, чтобы сразу добавлять записи через интерфейс:

# blog/admin.py
from django.contrib import admin

from .models import Post


@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ['title', 'created_at']
    search_fields = ['title']

Подробнее о полях и связях — в статье «Модели Django», о запросах к базе — в шпаргалке по QuerySet, о настройке админки — в руководстве по Django Admin.

Как создать приложение в подпапке

В больших проектах приложения складывают в общую папку, например apps/. Каталог назначения передают вторым аргументом. В Django 5.2 он должен существовать заранее, Django 6.x создаёт его сам — команда mkdir ниже подходит для обеих версий:

Windows:

mkdir apps\shop
python manage.py startapp shop apps\shop

macOS и Linux:

mkdir -p apps/shop
python manage.py startapp shop apps/shop

Пустой файл apps/__init__.py не обязателен, но его обычно добавляют, чтобы apps был обычным Python-пакетом. Главное — исправить name в конфигурации: startapp записывает туда только 'shop', а нужен полный путь импорта:

# apps/shop/apps.py
from django.apps import AppConfig


class ShopConfig(AppConfig):
    name = 'apps.shop'

# config/settings.py
INSTALLED_APPS = [
    # ...
    'apps.shop',
]

Если забыть поправить name, при запуске получите ImproperlyConfigured: Cannot import 'shop'. Check that 'apps.shop.apps.ShopConfig.name' is correct.

Частые ошибки при создании приложения

No installed app with label ‘blog’

makemigrations blog или migrate blog не находят приложение — его нет в INSTALLED_APPS. Добавьте его и повторите команду.

Model class doesn’t declare an explicit app_label

RuntimeError: Model class blog.models.Post doesn't declare an explicit app_label and isn't in an application in INSTALLED_APPS.

Та же причина: модель импортируется, но приложение не зарегистрировано.

TemplateDoesNotExist: blog/about.html

Проверьте по порядку: приложение есть в INSTALLED_APPS; шаблон лежит в blog/templates/blog/about.html (две папки — templates и blog); в render() указан путь 'blog/about.html'; в TEMPLATES стоит 'APP_DIRS': True.

conflicts with the name of an existing Python module

CommandError: 'test' conflicts with the name of an existing Python module and cannot be used as an app name.

Имя занято модулем стандартной библиотеки или уже существующей папкой: test, email, site, а также имя пакета проекта (config) или уже созданного приложения. Выберите другое имя.

is not a valid app name

Имя содержит дефис, пробел или начинается с цифры: my-app → my_app.

Страница приложения отдаёт 404

Сервер разработки перезапускается автоматически, но новый urls.py нужно подключить через include() в корневом urls.py — иначе Django о нём не узнает. Если страница отдаёт 404, откройте её при DEBUG = True: Django покажет список всех маршрутов, которые он перебрал.

Чек-лист нового приложения

• python manage.py startapp <имя> выполнен в папке с manage.py
• приложение добавлено в INSTALLED_APPS
• создан urls.py приложения и подключён через include()
• шаблоны лежат в templates/<имя_приложения>/
• после изменения моделей выполнены makemigrations и migrate
• модели зарегистрированы в admin.py

Частые вопросы

Сколько приложений создавать в проекте?

Столько, сколько у сайта самостоятельных областей: блог, каталог, заказы, аккаунты. Удобная проверка — назначение приложения описывается одним предложением без союза «и». Небольшому сайту хватает одного-двух приложений; дробить код раньше времени не нужно.

Как удалить приложение Django?

Сначала откатите его миграции, чтобы удалить таблицы из базы, затем уберите приложение из INSTALLED_APPS, удалите его include() из корневого urls.py и папку с кодом:

python manage.py migrate blog zero

Если на модели приложения ссылаются другие приложения (ForeignKey, импорты), сначала уберите эти связи и создайте для них миграции.

Как переименовать приложение и не потерять данные?

Таблицы и история миграций привязаны к метке приложения (label), которая по умолчанию совпадает с последней частью name. Переименуйте папку и name, но сохраните старую метку:

# articles/apps.py — бывшее приложение blog
class ArticlesConfig(AppConfig):
    name = 'articles'
    label = 'blog'

Таблицы blog_post и записи о миграциях останутся прежними; останется заменить импорты blog. на articles. в коде.

Можно ли создать приложение без startapp?

Да. Приложение Django — обычный Python-пакет, указанный в INSTALLED_APPS; startapp только генерирует типовые файлы. Папки с __init__.py достаточно, а models.py, apps.py и migrations/ добавляют по мере надобности.

Где подключать сигналы приложения?

В методе ready() класса конфигурации: Django вызывает его, когда все приложения загружены. Обработчики держат в отдельном модуле signals.py и импортируют его так:

# blog/apps.py
from django.apps import AppConfig


class BlogConfig(AppConfig):
    name = 'blog'

    def ready(self):
        from . import signals  # noqa: F401

Итог

Приложение Django создаётся командой python manage.py startapp, но начинает работать только после добавления в INSTALLED_APPS и подключения своих URL через include(). Держите в каждом приложении одну область ответственности — так проект проще развивать и тестировать.

Следующие шаги — модели Django и админка. Общая картина фреймворка и маршрут изучения — в руководстве «Django для начинающих».