Настройки

Основные настройки
Авторизация
Сообщения
Сессии
Сайты
Статические файлы
Индекс основных настроек по темам

Предупреждение

Будьте осторожны при перезаписи настроек, особенно когда значение по умолчанию — это непустой список или словарь, например, STATICFILES_FINDERS. Убедитесь, что вы сохранили компоненты, необходимые для функций Django, которые вы хотите использовать.

Основные настройки

Вот список настроек, доступных в ядре Django, и их значения по умолчанию. Настройки, предоставленные приложениями contrib, перечислены ниже, за которыми следует тематический индекс основных настроек. Для вводного материала см. руководство по теме настроек.

`ABSOLUTE_URL_OVERRIDES`

Значение по умолчанию: {} (Пустой словарь)

Словарь, сопоставляющий "app_label.model_name" строки с функциями, которые принимают объект модели и возвращают его URL. Это способ вставки или перезаписи get_absolute_url() методов на основе конкретной установки. Пример:

ABSOLUTE_URL_OVERRIDES = {
    'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,
    'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
}

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

`ADMINS`

Значение по умолчанию: [] (Пустой список)

Список всех людей, которые получают уведомления об ошибках кода. Когда DEBUG=False и AdminEmailHandler настроены в LOGGING (по умолчанию), Django отправляет этим людям подробности исключений, возникших в цикле запроса/ответа.

Каждый элемент в списке должен быть кортежем (Полное имя, адрес электронной почты). Пример:

[('John', 'john@example.com'), ('Mary', 'mary@example.com')]

`ALLOWED_HOSTS`

Значение по умолчанию: [] (Пустой список)

Список строк, представляющих имена хостов/доменов, которые может обслуживать этот сайт Django. Это мера безопасности для предотвращения атак с использованием заголовка HTTP Host, которые возможны даже в большинстве, казалось бы, безопасных конфигураций веб-сервера.

Значения в этом списке могут быть полными именами (например, 'www.example.com'), в этом случае они будут точно сопоставляться с заголовком запроса Host (регистронезависимо, без порта). Значение, начинающееся с точки, может использоваться как поддоменная маска: '.example.com' будет соответствовать example.com, www.example.com и любому другому поддомену example.com. Значение '*' будет соответствовать чему угодно; в этом случае вы несете ответственность за предоставление собственной валидации заголовка Host (возможно, в промежуточном ПО; если это так, то это промежуточное ПО должно быть указано первым в MIDDLEWARE).

Django также допускает полное доменное имя (FQDN) любых записей. Некоторые браузеры включают конечную точку в заголовке Host, которую Django удаляет при проверке хоста.

Если заголовок Host (или X-Forwarded-Host, если USE_X_FORWARDED_HOST включен) не соответствует ни одному значению в этом списке, метод django.http.HttpRequest.get_host() вызовет SuspiciousOperation.

Когда DEBUG имеет значение True, а ALLOWED_HOSTS пусто, хост проверяется на соответствие ['.localhost', '127.0.0.1', '[::1]'].

ALLOWED_HOSTS также проверяется при выполнении тестов.

Эта проверка применяется только через get_host(); если ваш код обращается к заголовку Host напрямую из request.META, вы обходите эту защиту безопасности.

Изменено в Django 3.1:

Если ALLOWED_HOSTS пустой, а DEBUG=True, поддомены localhost были разрешены.

`APPEND_SLASH`

Значение по умолчанию: True

Если установлено в True, если URL запроса не соответствует ни одному из шаблонов в URLconf и не заканчивается косой чертой, выполняется перенаправление HTTP на тот же URL с добавленной косой чертой. Обратите внимание, что перенаправление может привести к потере любых данных, отправленных в запросе POST.

Настройка APPEND_SLASH используется только в том случае, если установлено CommonMiddleware (см. Промежуточное ПО). См. также PREPEND_WWW.

`CACHES`

Значение по умолчанию:

{
    'default': {
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
    }
}

Словарь, содержащий настройки всех кэшей, которые будут использоваться с Django. Это вложенный словарь, содержимое которого сопоставляет псевдонимы кэшей со словарем, содержащим параметры для отдельного кэша.

Настройка CACHES должна настроить кэш default; также можно указать любое количество дополнительных кэшей. Если вы используете кэш-бекенд, отличный от локального кэша памяти, или вам нужно определить несколько кэшей, потребуются другие параметры. Доступны следующие параметры кэша.

`BACKEND`

Значение по умолчанию: '' (Пустая строка)

Используемый кэш-бекенд. Встроенные кэш-бекенды:

'django.core.cache.backends.db.DatabaseCache'
'django.core.cache.backends.dummy.DummyCache'
'django.core.cache.backends.filebased.FileBasedCache'
'django.core.cache.backends.locmem.LocMemCache'
'django.core.cache.backends.memcached.PyMemcacheCache'
'django.core.cache.backends.memcached.PyLibMCCache'

Вы можете использовать кэш-бекенд, не поставляемый с Django, установив BACKEND на полное квалифицированное имя класса кэш-бекенда (например, mypackage.backends.whatever.WhateverCache).

Изменено в Django 3.2:

Бекенд PyMemcacheCache был добавлен.

`KEY_FUNCTION`

Строка, содержащая путь с точкой к функции (или любому вызываемому объекту), которая определяет, как составить префикс, версию и ключ в окончательный ключ кэша. Реализация по умолчанию эквивалентна функции:

def make_key(key, key_prefix, version):
    return ':'.join([key_prefix, str(version), key])

Вы можете использовать любую функцию ключа, которую хотите, при условии, что у нее есть такая же сигнатура аргументов.

См. документацию по кэшу для получения дополнительной информации.

`KEY_PREFIX`

Значение по умолчанию: '' (Пустая строка)

Строка, которая будет автоматически включена (вставлена по умолчанию) во все ключи кэша, используемые сервером Django.

См. документацию по кэшу для получения дополнительной информации.

`LOCATION`

Значение по умолчанию: '' (Пустая строка)

Расположение кэша для использования. Это может быть каталог для кэша файловой системы, хост и порт для сервера memcache или идентификационное имя для локального кэша памяти. Например:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': '/var/tmp/django_cache',
    }
}

`OPTIONS`

Значение по умолчанию: None

Дополнительные параметры для передачи кэш-бекенду. Доступные параметры зависят от вашего кэш-бекенда.

Некоторую информацию о доступных параметрах можно найти в документации по параметрам кэша. Для получения дополнительной информации см. документацию модуля вашего бэкенда.

`TIMEOUT`

Значение по умолчанию: 300

Количество секунд, по истечении которых запись кэша считается устаревшей. Если значение этой настройки None, записи кэша не будут истекать.

`VERSION`

Значение по умолчанию: 1

Номер версии по умолчанию для ключей кэша, сгенерированных сервером Django.

См. документацию по кэшу для получения дополнительной информации.

`CACHE_MIDDLEWARE_ALIAS`

Значение по умолчанию: 'default'

Подключение к кэшу, используемое для промежуточного ПО кэша.

`CACHE_MIDDLEWARE_KEY_PREFIX`

Значение по умолчанию: '' (Пустая строка)

Строка, которая будет добавлена в качестве префикса к ключам кэша, генерируемым промежуточным ПО кэша. Этот префикс комбинируется с настройкой KEY_PREFIX; он не заменяет его.

См. рамку кэширования Django.

`CACHE_MIDDLEWARE_SECONDS`

По умолчанию: 600

Значение по умолчанию для количества секунд кеширования страницы для кеширования по сайту.

См. фреймворк кэширования Django.

`CSRF_COOKIE_AGE`

По умолчанию: 31449600 (примерно 1 год, в секундах)

Срок действия куки CSRF в секундах.

Причина установки длительного срока истечения срока действия — избежать проблем в случае закрытия браузера пользователем или добавления страницы в закладки, а затем загрузки этой страницы из кэша браузера. Без постоянных куки отправка формы в этом случае завершится неудачей.

Некоторые браузеры (в частности, Internet Explorer) могут запретить использование постоянных куки или повредить индексы файла cookie на диске, из-за чего проверки защиты CSRF (иногда прерывисто) могут завершиться неудачей. Измените это значение на None, чтобы использовать куки CSRF на основе сеанса, которые хранят куки в памяти вместо постоянного хранилища.

`CSRF_COOKIE_DOMAIN`

По умолчанию: None

Домен, используемый при установке куки CSRF. Это может быть полезно для простого исключения запросов с разных поддоменов из обычной защиты от подделки межсайтовых запросов. Его следует установить на строку, например, ".example.com", чтобы разрешить POST-запрос из формы на одном поддомене, который будет принят представлением, обслуживаемым с другого поддомена.

Обратите внимание, что наличие этого параметра не подразумевает, что защита Django от подделки межсайтовых запросов по умолчанию защищена от атак с разных поддоменов — см. раздел ограничения CSRF.

`CSRF_COOKIE_HTTPONLY`

По умолчанию: False

Использовать флаг HttpOnly для куки CSRF. Если это значение установлено как True, клиентский JavaScript не сможет получить доступ к куки CSRF.

Отмечение куки CSRF как HttpOnly не обеспечивает никакой практической защиты, так как CSRF предназначен только для защиты от атак с разных доменов. Если злоумышленник может прочитать куки через JavaScript, он уже находится в том же домене, что и браузер, поэтому он может делать все, что захочет. (XSS — намного большая проблема, чем CSRF.)

Хотя настройка малоэффективна, её иногда требуют аудиторы безопасности.

Если вы включили это и вам нужно отправить значение маркера CSRF с AJAX-запросом, ваш JavaScript должен извлечь значение из скрытого поля формы маркера CSRF, а не из куки.

См. SESSION_COOKIE_HTTPONLY для получения подробностей о HttpOnly.

`CSRF_COOKIE_NAME`

По умолчанию: 'csrftoken'

Имя куки для использования маркера аутентификации CSRF. Это может быть любое имя (только если оно отличается от других имён куки в вашем приложении). См. Защита от подделки межсайтовых запросов.

`CSRF_COOKIE_PATH`

По умолчанию: '/'

Путь, установленный в куки CSRF. Он должен соответствовать пути URL вашего установленного Django или быть его предком.

Это полезно, если у вас несколько экземпляров Django работают под одним и тем же именем хоста. Они могут использовать разные пути куки, и каждый экземпляр увидит только свою собственную куки CSRF.

`CSRF_COOKIE_SAMESITE`

По умолчанию: 'Lax'

Значение флага SameSite в куки CSRF. Этот флаг предотвращает отправку куки в запросах с разных сайтов.

См. SESSION_COOKIE_SAMESITE для получения подробностей о SameSite.

Изменено в Django 3.1:

Разрешено значение CSRF_COOKIE_SAMESITE = 'None'.

`CSRF_COOKIE_SECURE`

По умолчанию: False

Использовать безопасную куки для куки CSRF. Если установлено значение True, куки будет отмечена как «безопасная», что означает, что браузеры могут убедиться, что куки отправляются только с подключением HTTPS.

`CSRF_USE_SESSIONS`

По умолчанию: False

Хранить маркер CSRF в сессии пользователя вместо куки. Требует использования django.contrib.sessions.

Хранение маркера CSRF в куки (по умолчанию в Django) безопасно, но хранение в сессии является распространённой практикой в других фреймворках и поэтому иногда требуется аудиторами безопасности.

Поскольку представления по умолчанию для ошибок требуют маркер CSRF, SessionMiddleware должен быть указан в MIDDLEWARE перед любым средством, которое может вызвать исключение для запуска представления об ошибке (например, PermissionDenied), если вы используете CSRF_USE_SESSIONS. См. Порядок обработки данных посредством.

`CSRF_FAILURE_VIEW`

По умолчанию: 'django.views.csrf.csrf_failure'

Путь к функции представления, которая используется, когда входящий запрос отклоняется защитой от подделки межсайтовых запросов защитой от подделки межсайтовых запросов. Функция должна иметь следующий вид:

def csrf_failure(request, reason=""):
    ...

где reason — краткое сообщение (предназначенное для разработчиков или регистрации, а не для конечных пользователей), указывающее причину отклонения запроса. Она должна возвращать HttpResponseForbidden.

django.views.csrf.csrf_failure() принимает дополнительный template_name параметр, который по умолчанию имеет значение '403_csrf.html'. Если шаблон с таким именем существует, он будет использован для рендеринга страницы.

`CSRF_HEADER_NAME`

По умолчанию: 'HTTP_X_CSRFTOKEN'

Имя заголовка запроса, используемого для аутентификации CSRF.

Как и другие заголовки HTTP в request.META, имя заголовка, полученное от сервера, нормализуется путём преобразования всех символов в верхний регистр, замены тире на подчеркивания и добавления префикса 'HTTP_' к имени. Например, если ваш клиент отправляет заголовок 'X-XSRF-TOKEN', настройка должна быть 'HTTP_X_XSRF_TOKEN'.

`CSRF_TRUSTED_ORIGINS`

По умолчанию: [] (Пустой список)

Список хостов, которые являются надёжными источниками для небезопасных запросов (например, POST). Для небезопасного запроса secure защита CSRF Django требует, чтобы запрос имел заголовок Referer, который соответствует источнику в заголовке Host. Это предотвращает, например, запрос POST с subdomain.example.com от успешного выполнения против api.example.com. Если вам нужны запросы с разных источников через HTTPS, например, добавьте "subdomain.example.com" в этот список. Настройка также поддерживает поддомены, поэтому вы можете добавить ".example.com", чтобы разрешить доступ со всех поддоменов example.com.

`DATABASES`

По умолчанию: {} (Пустой словарь)

Словарь, содержащий настройки всех баз данных, которые будут использоваться с Django. Это вложенный словарь, содержимое которого отображает псевдоним базы данных на словарь, содержащий параметры отдельной базы данных.

Настройка DATABASES должна настроить базу данных default; также можно указать любое количество дополнительных баз данных.

Самый простой возможный файл настроек для однобазовой конфигурации с использованием SQLite. Это можно настроить следующим образом:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': 'mydatabase',
    }
}

При подключении к другим базам данных, таким как MariaDB, MySQL, Oracle или PostgreSQL, потребуются дополнительные параметры подключения. См. настройку ENGINE ниже, чтобы указать другие типы баз данных. Этот пример для PostgreSQL:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydatabase',
        'USER': 'mydatabaseuser',
        'PASSWORD': 'mypassword',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

Следующие внутренние параметры, которые могут потребоваться для более сложных конфигураций, доступны:

`ATOMIC_REQUESTS`

По умолчанию: False

Установите это значение в True, чтобы обернуть каждое представление транзакцией в этой базе данных. См. Связывание транзакций с HTTP-запросами.

`AUTOCOMMIT`

По умолчанию: True

Установите это значение в False, если вы хотите отключить управление транзакциями Django и реализовать собственное.

`ENGINE`

По умолчанию: '' (Пустая строка)

Используемый бэкэнд базы данных. Встроенные бэкэнды баз данных:

'django.db.backends.postgresql'
'django.db.backends.mysql'
'django.db.backends.sqlite3'
'django.db.backends.oracle'

Вы можете использовать бэкэнд базы данных, который не поставляется с Django, установив ENGINE на полный путь (например, mypackage.backends.whatever).

END_OF_DOCUMENT_MARKER

`HOST`

По умолчанию: '' (пустая строка)

Хост, используемый при подключении к базе данных. Пустая строка означает localhost. Не используется с SQLite.

Если это значение начинается с прямой косой черты ('/') и вы используете MySQL, MySQL подключится через сокет Unix к указанному сокету. Например:

"HOST": '/var/run/mysql'

Если вы используете MySQL и это значение не начинается с прямой косой черты, тогда это значение считается именем хоста.

Если вы используете PostgreSQL, по умолчанию (пустая HOST), подключение к базе данных выполняется через сокеты доменной области UNIX («локальные» строки в pg_hba.conf). Если ваш сокет доменной области UNIX находится не в стандартном расположении, используйте то же значение unix_socket_directory из postgresql.conf. Если вы хотите подключиться через сокеты TCP, установите HOST на ‘localhost’ или ‘127.0.0.1’ («строки хоста» в pg_hba.conf). В Windows вы всегда должны определять HOST, так как сокеты доменной области UNIX недоступны.

`NAME`

По умолчанию: '' (пустая строка)

Имя базы данных для использования. Для SQLite это полный путь к файлу базы данных. При указании пути всегда используйте прямые косые черты, даже в Windows (например, C:/homes/user/mysite/sqlite3.db).

`CONN_MAX_AGE`

По умолчанию: 0

Срок жизни подключения к базе данных, в секундах (целое число). Используйте 0, чтобы закрывать подключения к базе данных в конце каждого запроса — историческое поведение Django, и None для неограниченных постоянных подключений.

`OPTIONS`

По умолчанию: {} (пустой словарь)

Дополнительные параметры для подключения к базе данных. Доступные параметры зависят от бэкенда вашей базы данных.

Некоторая информация о доступных параметрах представлена в документации по Базам данных. Для получения дополнительной информации обратитесь к документации модуля бэкенда.

`PASSWORD`

По умолчанию: '' (пустая строка)

Пароль для подключения к базе данных. Не используется с SQLite.

`PORT`

По умолчанию: '' (пустая строка)

Порт для подключения к базе данных. Пустая строка означает порт по умолчанию. Не используется с SQLite.

`TIME_ZONE`

По умолчанию: None

Строка, представляющая часовой пояс для этого подключения к базе данных или None. Этот внутренний параметр настройки DATABASES принимает те же значения, что и общий параметр TIME_ZONE.

Когда USE_TZ равно True и этот параметр задан, чтение дат и времени из базы данных возвращает даты и время с учетом часового пояса в этом часовом поясе вместо UTC. Когда USE_TZ равно False, установка этого параметра является ошибкой.

Если бэкенд базы данных не поддерживает часовые пояса (например, SQLite, MySQL, Oracle), Django читает и записывает даты и время в местном времени в соответствии с этим параметром, если он задан, и в UTC, если нет. Изменение часового пояса подключения изменяет способ чтения и записи дат и времени в базе данных.
- Если Django управляет базой данных и у вас нет веских причин действовать иначе, оставьте этот параметр без значения. Лучше хранить даты и время в UTC, так как это позволяет избежать неоднозначных или несуществующих дат и времени во время перехода на летнее время. Кроме того, получение дат и времени в UTC упрощает арифметику дат и времени — нет необходимости в методе normalize(), предоставляемом pytz.
- Если вы подключаетесь к базе данных стороннего разработчика, в которой даты и время хранятся в местном времени, а не в UTC, вам необходимо установить этот параметр в соответствующий часовой пояс. Аналогично, если Django управляет базой данных, но системы сторонних разработчиков подключаются к той же базе данных и ожидают найти даты и время в местном времени, вам необходимо установить этот параметр.
Если бэкенд базы данных поддерживает часовые пояса (например, PostgreSQL), параметр TIME_ZONE очень редко требуется. Его можно изменить в любое время; база данных позаботится о преобразовании дат и времени в нужный часовой пояс.

Установка часового пояса подключения к базе данных может быть полезной для выполнения необработанных запросов SQL, связанных с функциями дат/времени, предоставляемыми базой данных, такими как date_trunc, так как их результаты зависят от часового пояса.

Однако это имеет недостаток: получение всех дат и времени в местном времени усложняет арифметику дат и времени — вам нужно вызвать метод normalize(), предоставляемый pytz, после каждой операции.

Рассмотрите возможность явного преобразования в местное время с помощью AT TIME ZONE в необработанных запросах SQL вместо установки параметра TIME_ZONE.

Изменено в Django 3.1:

Использование этого параметра, когда бэкенд базы данных поддерживает часовые пояса, было разрешено.

`DISABLE_SERVER_SIDE_CURSORS`

По умолчанию: False

Установите это значение в True, если вы хотите отключить использование курсоров на стороне сервера с QuerySet.iterator(). Пулы транзакций и курсоры на стороне сервера описывает случай использования.

Это параметр, специфичный для PostgreSQL.

`USER`

По умолчанию: '' (пустая строка)

Имя пользователя для подключения к базе данных. Не используется с SQLite.

`TEST`

По умолчанию: {} (пустой словарь)

Словарь настроек для тестовых баз данных; для получения более подробной информации о создании и использовании тестовых баз данных, см. Тестовая база данных.

Вот пример с конфигурацией тестовой базы данных:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'USER': 'mydatabaseuser',
        'NAME': 'mydatabase',
        'TEST': {
            'NAME': 'mytestdatabase',
        },
    },
}

Следующие ключи в словаре TEST доступны:

`CHARSET`

По умолчанию: None

Кодировка набора символов, используемая для создания тестовой базы данных. Значение этой строки передается напрямую в базу данных, поэтому ее формат зависит от бэкенда.

Поддерживается бэкендами PostgreSQL (postgresql) и MySQL (mysql).

`COLLATION`

По умолчанию: None

Порядок сортировки, используемый при создании тестовой базы данных. Это значение передается непосредственно в бэкенд, поэтому его формат зависит от бэкенда.

Поддерживается только для бэкенда mysql (см. руководство по MySQL для получения подробностей).

`DEPENDENCIES`

По умолчанию: ['default'] для всех баз данных, кроме default, у которой нет зависимостей.

Зависимости создания базы данных. См. документацию по управлению порядком создания тестовых баз данных для получения подробностей.

`MIGRATE`

Добавлено в Django 3.1.

По умолчанию: True

Если установлено в False, миграции не будут выполняться при создании тестовой базы данных. Это аналогично установке None как значения в MIGRATION_MODULES, но для всех приложений.

`MIRROR`

По умолчанию: None

Псевдоним базы данных, который эта база данных должна дублировать во время тестирования.

Эта настройка существует для тестирования конфигураций «главный/реплика» (называемых «мастер/слейв» некоторыми базами данных) нескольких баз данных. См. документацию по тестированию конфигураций «главный/реплика» для получения подробностей.

`NAME`

По умолчанию: None

Имя базы данных для использования при запуске набора тестов.

Если используется значение по умолчанию (None) с движком базы данных SQLite, тесты будут использовать базу данных в памяти. Для всех других движков баз данных тестовая база данных будет использовать имя 'test_' + DATABASE_NAME.

См. Тестовую базу данных.

`SERIALIZE`

Булево значение для управления сериализацией стандартного тестового исполнителя базы данных в строку JSON в памяти перед запуском тестов (используется для восстановления состояния базы данных между тестами, если у вас нет транзакций). Вы можете установить это в False, чтобы ускорить время создания, если у вас нет классов тестов с serialized_rollback=True.

`TEMPLATE`

Это настройка, специфичная для PostgreSQL.

Имя шаблона (например, 'template0'), из которого должна быть создана тестовая база данных.