Как создать проект Django: команда startproject и первый запуск

Новый проект Django создаётся одной командой: django-admin startproject config . — она генерирует manage.py и пакет с настройками. После этого достаточно применить миграции и запустить сервер разработки, чтобы открыть сайт по адресу http://127.0.0.1:8000/.

django-admin startproject config .
python manage.py migrate
python manage.py runserver

Ниже — создание проекта Django по шагам, разбор каждого сгенерированного файла, настройки, которые стоит поменять сразу, и запуск уже существующего проекта, например склонированного из Git. Команды проверены на Django 6.1 и 5.2 LTS.

Подготовка: окружение и Django

Команда startproject входит в утилиту django-admin, которая появляется после установки фреймворка. Если Django ещё не установлен, пройдите пошаговую установку Django. Коротко:

Windows:

mkdir mysite
cd mysite
py -m venv .venv
.venv\Scripts\activate
python -m pip install django

macOS и Linux:

mkdir mysite
cd mysite
python3 -m venv .venv
source .venv/bin/activate
python -m pip install django

Все команды ниже выполняются в активированном виртуальном окружении, поэтому python везде указывает на его интерпретатор.

Создание проекта: startproject с точкой и без

Синтаксис команды:

django-admin startproject <имя> [каталог]

<имя> — название Python-пакета с настройками, [каталог] — куда положить файлы. От второго аргумента зависит структура проекта.

С точкой: плоская структура (рекомендуем)

Точка означает «текущая папка». Если вы уже находитесь в папке mysite с окружением .venv, выполните:

django-admin startproject config .

Получится плоская структура без лишней вложенности:

mysite/
├── .venv/
├── manage.py
└── config/
    ├── __init__.py
    ├── asgi.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

Имя config — популярное соглашение: пакет содержит именно конфигурацию, а бизнес-логика живёт в приложениях. Можно назвать его и иначе, например по имени проекта.

Без точки: вложенная папка проекта

django-admin startproject mysite

Django создаст папку mysite, а внутри — пакет с тем же именем:

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

Так устроен проект в официальном туториале. Работает он так же, но две папки mysite/mysite часто путают новичков. Внешнюю папку можно переименовать как угодно — Django она не важна. Внутренний пакет переименовывать нельзя без правки manage.py, settings.py, asgi.py и wsgi.py.

Совет: в Django 6.x каталог из второго аргумента создаётся автоматически, если его нет. В Django 5.2 он должен существовать заранее, иначе команда завершится ошибкой Destination directory ... does not exist, please create it first.

Структура проекта Django: что за файлы

Файл	Назначение
manage.py	Точка входа для команд проекта: runserver, migrate, startapp, createsuperuser и др.
config/__init__.py	Делает папку Python-пакетом
config/settings.py	Все настройки проекта: приложения, middleware, база данных, шаблоны, язык, статика
config/urls.py	Корневая таблица URL — отсюда запрос направляется во view или в urls.py приложений
config/wsgi.py	Точка входа для WSGI-серверов (Gunicorn, uWSGI) в продакшне
config/asgi.py	Точка входа для ASGI-серверов (Uvicorn, Daphne) — нужна для асинхронного кода и WebSocket

manage.py делает то же, что django-admin, но дополнительно указывает Django, где лежат настройки проекта (переменная DJANGO_SETTINGS_MODULE). Поэтому после создания проекта все команды запускают через python manage.py ....

Корневой urls.py из коробки содержит один маршрут — админку:

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

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

Первый запуск проекта Django

Сначала примените миграции

Встроенные приложения (пользователи, сессии, админка) хранят данные в базе. По умолчанию это файл SQLite db.sqlite3 в корне проекта. Создайте таблицы:

python manage.py migrate

Operations to perform:
  Apply all migrations: admin, auth, contenttypes, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  ...
  Applying sessions.0001_initial... OK

Если пропустить миграции, сервер всё равно запустится, но предупредит: You have 18 unapplied migration(s), а вход в админку не заработает.

Запустите сервер разработки

python manage.py runserver

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
Django version 6.1.2, using settings 'config.settings'
Starting WSGI development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.

Откройте http://127.0.0.1:8000/ — появится стартовая страница с ракетой и надписью «The install worked successfully! Congratulations!». Остановить сервер можно сочетанием Ctrl+C (на Windows подсказка предлагает Ctrl+Break, но Ctrl+C тоже работает).

Сервер разработки сам перезапускается при изменении .py-файлов. Он предназначен только для локальной работы — об этом прямо предупреждает строка WARNING: This is a development server в выводе. Для продакшна используют Gunicorn или Uvicorn за Nginx — см. деплой Django с Gunicorn и Nginx.

Другой порт и доступ из локальной сети

# другой порт
python manage.py runserver 8080

# слушать все интерфейсы, например чтобы открыть сайт с телефона в той же сети
python manage.py runserver 0.0.0.0:8000

Во втором случае добавьте IP-адрес компьютера в ALLOWED_HOSTS, иначе Django ответит ошибкой DisallowedHost. Пока DEBUG = True и список пуст, разрешены только localhost, 127.0.0.1 и [::1].

Создайте суперпользователя

Чтобы войти в админку по адресу /admin/, нужен администратор:

python manage.py createsuperuser

Подробности и неинтерактивный режим — в статье «Как создать суперпользователя Django».

Что настроить в settings.py сразу

Сгенерированный settings.py рассчитан на разработку. Три вещи стоит поправить в первый же день:

# config/settings.py
LANGUAGE_CODE = 'ru'
TIME_ZONE = 'Europe/Moscow'

Админка и сообщения валидации станут русскими, а время — местным. Третье — вынести SECRET_KEY из кода. В сгенерированном файле ключ записан прямо в коде с префиксом django-insecure-: для продакшна его заменяют и читают из переменной окружения.

import os

SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'django-insecure-dev-only')
DEBUG = os.environ.get('DJANGO_DEBUG', '') == '1'

В Django 5.2 в конце файла также есть DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'. В Django 6.0+ эта строка больше не генерируется: BigAutoField стал значением по умолчанию. А в Django 6.1 в шаблоне появилась настройка почты MAILERS с консольным бэкендом — письма в разработке выводятся в терминал.

Следующий шаг: первое приложение

Проект — это контейнер с настройками. Функциональность (модели, страницы, API) пишут в приложениях, которые создаются командой startapp:

python manage.py startapp blog

Как подключить приложение, написать первую view и шаблон — в статье «Как создать приложение в Django».

Как запустить существующий проект Django

Если проект уже написан (например, вы склонировали репозиторий), startproject не нужен. Порядок такой:

Windows:

git clone https://github.com/user/project.git
cd project
py -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

macOS и Linux:

git clone https://github.com/user/project.git
cd project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

Проверьте README проекта: часто нужно создать файл .env с переменными (секретный ключ, параметры базы данных) или поднять PostgreSQL. Команда python manage.py check быстро покажет ошибки конфигурации без запуска сервера.

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

is not a valid project name

CommandError: 'my-site' is not a valid project name. Please make sure the name is a valid identifier.

Имя проекта становится именем Python-пакета, поэтому дефисы, пробелы и цифры в начале недопустимы. Используйте my_site или mysite.

conflicts with the name of an existing Python module

CommandError: 'django' conflicts with the name of an existing Python module and cannot be used as a project name.

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

manage.py already exists

CommandError: ...\manage.py already exists. Overlaying a project into an existing directory won't replace conflicting files.

В папке уже есть проект. Django не перезаписывает файлы — создайте проект в пустой папке или удалите старые файлы вручную.

django-admin не распознано как команда

Окружение не активировано или Django установлен в другой Python. Активируйте .venv либо запустите утилиту как модуль: python -m django startproject config .. Подробнее — в разделе ошибок статьи об установке Django.

That port is already in use

Сообщение Error: That port is already in use. означает, что порт 8000 занят другим процессом — часто вторым забытым runserver в соседнем терминале. Остановите его или запустите сервер на другом порту: python manage.py runserver 8001.

На Windows это сообщение встречается редко. Если порт занят процессом другой программы, Windows отказывает в доступе, и Django пишет Error: You don't have permission to access that port. Та же ошибка появляется, когда порт входит в диапазон, зарезервированный системой (список показывает netsh interface ipv4 show excludedportrange protocol=tcp). А второй runserver на том же порту на Windows стартует без ошибки, и запросы может обрабатывать старый процесс. Если изменения «не применяются», проверьте, не запущен ли сервер дважды.

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

Куда пропала стартовая страница с ракетой?

Django показывает её, только пока DEBUG = True и в корневом urls.py нет маршрутов, кроме админки. Как только вы подключите свои URL, адрес / начнёт отдавать 404, пока для него не появится маршрут с пустым путём path('', ...). Проект при этом исправен.

Как переименовать пакет с настройками?

Переименуйте папку (например, config в core) и замените старое имя в четырёх местах: DJANGO_SETTINGS_MODULE в manage.py, asgi.py и wsgi.py, а также ROOT_URLCONF и WSGI_APPLICATION в settings.py. После правки запустите python manage.py check — команда сразу покажет пропущенную ссылку на старое имя.

Что добавить в .gitignore нового проекта?

Окружение, локальную базу, кеш байт-кода и файл с секретами — всё, что создаётся на конкретной машине:

.venv/
__pycache__/
db.sqlite3
.env

Вместо окружения в репозиторий кладут requirements.txt, а вместо базы — миграции.

Можно ли создать проект по своему шаблону?

Да, у startproject есть параметр --template: он принимает путь к папке или URL архива со структурой проекта. Так команды разворачивают заготовку с готовыми настройками, Docker-файлами и линтерами:

django-admin startproject --template=https://example.com/project-template.zip config .

Как создать проект Django в PyCharm или VS Code?

Теми же командами во встроенном терминале IDE: создайте и активируйте окружение, установите Django и выполните django-admin startproject config .. Затем укажите редактору интерпретатор из .venv, чтобы он видел установленный Django и не подсвечивал импорты как ошибки.

Итог

Чтобы создать проект Django, выполните django-admin startproject config . в папке с активированным окружением, затем migrate и runserver. Пакет config хранит настройки и корневые URL, а manage.py — точка входа для всех остальных команд.

Дальше — создание приложения командой startapp, а общий маршрут изучения фреймворка — в руководстве «Django для начинающих».