---- url: https://docs.djangoproject.com/en/6.1/ref/class-based-views/generic-date-based/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/class-based-views/generic-date-based/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/class-based-views/generic-date-based/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/class-based-views/generic-date-based/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/class-based-views/generic-date-based/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/class-based-views/generic-date-based/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/class-based-views/generic-date-based/) - [it](https://docs.djangoproject.com/it/6.1/ref/class-based-views/generic-date-based/) - [id](https://docs.djangoproject.com/id/6.1/ref/class-based-views/generic-date-based/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/class-based-views/generic-date-based/) - [es](https://docs.djangoproject.com/es/6.1/ref/class-based-views/generic-date-based/) - [el](https://docs.djangoproject.com/el/6.1/ref/class-based-views/generic-date-based/) * * [dev](https://docs.djangoproject.com/en/dev/ref/class-based-views/generic-date-based/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/class-based-views/generic-date-based/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/class-based-views/generic-date-based/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/class-based-views/generic-date-based/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/class-based-views/generic-date-based/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/class-based-views/generic-date-based/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/class-based-views/generic-date-based/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/class-based-views/generic-date-based/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/class-based-views/generic-date-based/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/class-based-views/generic-date-based/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/class-based-views/generic-date-based/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/class-based-views/generic-date-based/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/class-based-views/generic-date-based/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/class-based-views/generic-date-based/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/class-based-views/generic-date-based/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-date-based/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/class-based-views/generic-date-based/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/class-based-views/generic-date-based/) - [**](#top) # Generic date views[¶](#module-django.views.generic.dates "Link to this heading") Date-based generic views, provided in [`django.views.generic.dates`](#module-django.views.generic.dates "django.views.generic.dates"), are views for displaying drilldown pages for date-based data. Note Some of the examples on this page assume that an `Article` model has been defined as follows in `myapp/models.py`: ``` from django.db import models from django.urls import reverse class Article(models.Model): title = models.CharField(max_length=200) pub_date = models.DateField() def get_absolute_url(self): return reverse("article-detail", kwargs={"pk": self.pk}) ``` ## `ArchiveIndexView`[¶](#archiveindexview "Link to this heading") * *class *ArchiveIndexView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L413)[¶](#django.views.generic.dates.ArchiveIndexView "Link to this definition") A top-level index page showing the “latest” objects, by date. Objects with a date in the *future* are not included unless you set `allow_future` to `True`. **Ancestors (MRO)** * [`django.views.generic.list.MultipleObjectTemplateResponseMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectTemplateResponseMixin "django.views.generic.list.MultipleObjectTemplateResponseMixin") * [`django.views.generic.base.TemplateResponseMixin`](../mixins-simple/#django.views.generic.base.TemplateResponseMixin "django.views.generic.base.TemplateResponseMixin") * [`django.views.generic.dates.BaseArchiveIndexView`](#django.views.generic.dates.BaseArchiveIndexView "django.views.generic.dates.BaseArchiveIndexView") * [`django.views.generic.dates.BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView") * [`django.views.generic.list.MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") * [`django.views.generic.dates.DateMixin`](../mixins-date-based/#django.views.generic.dates.DateMixin "django.views.generic.dates.DateMixin") * [`django.views.generic.base.View`](../base/#django.views.generic.base.View "django.views.generic.base.View") **Context** In addition to the context provided by [`django.views.generic.list.MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") (via [`django.views.generic.dates.BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView")), the template’s context will be: * `date_list`: A [`QuerySet`](../../models/querysets/#django.db.models.query.QuerySet.dates "django.db.models.query.QuerySet.dates") object containing all years that have objects available according to `queryset`, represented as [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") objects, in descending order. **Notes** * Uses a default `context_object_name` of `latest`. * Uses a default `template_name_suffix` of `_archive`. * Defaults to providing `date_list` by year, but this can be altered to month or day using the attribute `date_list_period`. This also applies to all subclass views. **Example myapp/urls.py**: ``` from django.urls import path from django.views.generic.dates import ArchiveIndexView from myapp.models import Article urlpatterns = [ path( "archive/", ArchiveIndexView.as_view(model=Article, date_field="pub_date"), name="article_archive", ), ] ``` **Example myapp/article\_archive.html**: ``` ``` This will output all articles. ## `YearArchiveView`[¶](#yeararchiveview "Link to this heading") * *class *YearArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L469)[¶](#django.views.generic.dates.YearArchiveView "Link to this definition") A yearly archive page showing all available months in a given year. Objects with a date in the *future* are not displayed unless you set `allow_future` to `True`. **Ancestors (MRO)** * [`django.views.generic.list.MultipleObjectTemplateResponseMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectTemplateResponseMixin "django.views.generic.list.MultipleObjectTemplateResponseMixin") * [`django.views.generic.base.TemplateResponseMixin`](../mixins-simple/#django.views.generic.base.TemplateResponseMixin "django.views.generic.base.TemplateResponseMixin") * [`django.views.generic.dates.BaseYearArchiveView`](#django.views.generic.dates.BaseYearArchiveView "django.views.generic.dates.BaseYearArchiveView") * [`django.views.generic.dates.YearMixin`](../mixins-date-based/#django.views.generic.dates.YearMixin "django.views.generic.dates.YearMixin") * [`django.views.generic.dates.BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView") * [`django.views.generic.list.MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") * [`django.views.generic.dates.DateMixin`](../mixins-date-based/#django.views.generic.dates.DateMixin "django.views.generic.dates.DateMixin") * [`django.views.generic.base.View`](../base/#django.views.generic.base.View "django.views.generic.base.View") - make\_object\_list[¶](#django.views.generic.dates.YearArchiveView.make_object_list "Link to this definition") A boolean specifying whether to retrieve the full list of objects for this year and pass those to the template. If `True`, the list of objects will be made available to the context. If `False`, the `None` queryset will be used as the object list. By default, this is `False`. * get\_make\_object\_list()[¶](#django.views.generic.dates.YearArchiveView.get_make_object_list "Link to this definition") Determine if an object list will be returned as part of the context. Returns [`make_object_list`](#django.views.generic.dates.YearArchiveView.make_object_list "django.views.generic.dates.YearArchiveView.make_object_list") by default. **Context** In addition to the context provided by [`django.views.generic.list.MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") (via [`django.views.generic.dates.BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView")), the template’s context will be: * `date_list`: A [`QuerySet`](../../models/querysets/#django.db.models.query.QuerySet.dates "django.db.models.query.QuerySet.dates") object containing all months that have objects available according to `queryset`, represented as [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") objects, in ascending order. * `year`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the given year. * `next_year`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the next year, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). * `previous_year`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the previous year, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). **Notes** * Uses a default `template_name_suffix` of `_archive_year`. **Example myapp/views.py**: ``` from django.views.generic.dates import YearArchiveView from myapp.models import Article class ArticleYearArchiveView(YearArchiveView): queryset = Article.objects.all() date_field = "pub_date" make_object_list = True allow_future = True ``` **Example myapp/urls.py**: ``` from django.urls import path from myapp.views import ArticleYearArchiveView urlpatterns = [ path("/", ArticleYearArchiveView.as_view(), name="article_year_archive"), ] ``` **Example myapp/article\_archive\_year.html**: ```

All Articles for {{ year|date:"Y" }}

{% for obj in object_list %}

{{ obj.title }} - {{ obj.pub_date|date:"F j, Y" }}

{% endfor %}
``` ## `MonthArchiveView`[¶](#montharchiveview "Link to this heading") * *class *MonthArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L515)[¶](#django.views.generic.dates.MonthArchiveView "Link to this definition") A monthly archive page showing all objects in a given month. Objects with a date in the *future* are not displayed unless you set `allow_future` to `True`. **Ancestors (MRO)** * [`django.views.generic.list.MultipleObjectTemplateResponseMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectTemplateResponseMixin "django.views.generic.list.MultipleObjectTemplateResponseMixin") * [`django.views.generic.base.TemplateResponseMixin`](../mixins-simple/#django.views.generic.base.TemplateResponseMixin "django.views.generic.base.TemplateResponseMixin") * [`django.views.generic.dates.BaseMonthArchiveView`](#django.views.generic.dates.BaseMonthArchiveView "django.views.generic.dates.BaseMonthArchiveView") * [`django.views.generic.dates.YearMixin`](../mixins-date-based/#django.views.generic.dates.YearMixin "django.views.generic.dates.YearMixin") * [`django.views.generic.dates.MonthMixin`](../mixins-date-based/#django.views.generic.dates.MonthMixin "django.views.generic.dates.MonthMixin") * [`django.views.generic.dates.BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView") * [`django.views.generic.list.MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") * [`django.views.generic.dates.DateMixin`](../mixins-date-based/#django.views.generic.dates.DateMixin "django.views.generic.dates.DateMixin") * [`django.views.generic.base.View`](../base/#django.views.generic.base.View "django.views.generic.base.View") **Context** In addition to the context provided by [`MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") (via [`BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView")), the template’s context will be: * `date_list`: A [`QuerySet`](../../models/querysets/#django.db.models.query.QuerySet.dates "django.db.models.query.QuerySet.dates") object containing all days that have objects available in the given month, according to `queryset`, represented as [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") objects, in ascending order. * `month`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the given month. * `next_month`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the next month, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). * `previous_month`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the previous month, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). **Notes** * Uses a default `template_name_suffix` of `_archive_month`. **Example myapp/views.py**: ``` from django.views.generic.dates import MonthArchiveView from myapp.models import Article class ArticleMonthArchiveView(MonthArchiveView): queryset = Article.objects.all() date_field = "pub_date" allow_future = True ``` **Example myapp/urls.py**: ``` from django.urls import path from myapp.views import ArticleMonthArchiveView urlpatterns = [ # Example: /2012/08/ path( "//", ArticleMonthArchiveView.as_view(month_format="%m"), name="archive_month_numeric", ), # Example: /2012/aug/ path( "//", ArticleMonthArchiveView.as_view(), name="archive_month", ), ] ``` **Example myapp/article\_archive\_month.html**: ```
    {% for article in object_list %}
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • {% endfor %}

{% if previous_month %} Previous Month: {{ previous_month|date:"F Y" }} {% endif %} {% if next_month %} Next Month: {{ next_month|date:"F Y" }} {% endif %}

``` ## `WeekArchiveView`[¶](#weekarchiveview "Link to this heading") * *class *WeekArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L577)[¶](#django.views.generic.dates.WeekArchiveView "Link to this definition") A weekly archive page showing all objects in a given week. Objects with a date in the *future* are not displayed unless you set `allow_future` to `True`. **Ancestors (MRO)** * [`django.views.generic.list.MultipleObjectTemplateResponseMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectTemplateResponseMixin "django.views.generic.list.MultipleObjectTemplateResponseMixin") * [`django.views.generic.base.TemplateResponseMixin`](../mixins-simple/#django.views.generic.base.TemplateResponseMixin "django.views.generic.base.TemplateResponseMixin") * [`django.views.generic.dates.BaseWeekArchiveView`](#django.views.generic.dates.BaseWeekArchiveView "django.views.generic.dates.BaseWeekArchiveView") * [`django.views.generic.dates.YearMixin`](../mixins-date-based/#django.views.generic.dates.YearMixin "django.views.generic.dates.YearMixin") * [`django.views.generic.dates.WeekMixin`](../mixins-date-based/#django.views.generic.dates.WeekMixin "django.views.generic.dates.WeekMixin") * [`django.views.generic.dates.BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView") * [`django.views.generic.list.MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") * [`django.views.generic.dates.DateMixin`](../mixins-date-based/#django.views.generic.dates.DateMixin "django.views.generic.dates.DateMixin") * [`django.views.generic.base.View`](../base/#django.views.generic.base.View "django.views.generic.base.View") **Context** In addition to the context provided by [`MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") (via [`BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView")), the template’s context will be: * `week`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the given week. * `next_week`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the next week, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). * `previous_week`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the previous week, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). **Notes** * Uses a default `template_name_suffix` of `_archive_week`. * The `week_format` attribute is a [`strptime()`](https://docs.python.org/3/library/time.html#time.strptime "(in Python v3.15)") format string used to parse the week number. The following values are supported: * `'%U'`: Based on the United States week system where the week begins on Sunday. This is the default value. * `'%W'`: Similar to `'%U'`, except it assumes that the week begins on Monday. This is not the same as the ISO 8601 week number. * `'%V'`: ISO 8601 week number where the week begins on Monday. **Example myapp/views.py**: ``` from django.views.generic.dates import WeekArchiveView from myapp.models import Article class ArticleWeekArchiveView(WeekArchiveView): queryset = Article.objects.all() date_field = "pub_date" week_format = "%W" allow_future = True ``` **Example myapp/urls.py**: ``` from django.urls import path from myapp.views import ArticleWeekArchiveView urlpatterns = [ # Example: /2012/week/23/ path( "/week//", ArticleWeekArchiveView.as_view(), name="archive_week", ), ] ``` **Example myapp/article\_archive\_week.html**: ```

Week {{ week|date:'W' }}

    {% for article in object_list %}
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • {% endfor %}

{% if previous_week %} Previous Week: {{ previous_week|date:"W" }} of year {{ previous_week|date:"Y" }} {% endif %} {% if previous_week and next_week %}--{% endif %} {% if next_week %} Next week: {{ next_week|date:"W" }} of year {{ next_week|date:"Y" }} {% endif %}

``` In this example, you are outputting the week number. Keep in mind that week numbers computed by the [`date`](../../templates/builtins/#std-templatefilter-date) template filter with the `'W'` format character are not always the same as those computed by [`strftime()`](https://docs.python.org/3/library/time.html#time.strftime "(in Python v3.15)") and [`strptime()`](https://docs.python.org/3/library/time.html#time.strptime "(in Python v3.15)") with the `'%W'` format string. For year 2015, for example, week numbers output by [`date`](../../templates/builtins/#std-templatefilter-date) are higher by one compared to those output by [`strftime()`](https://docs.python.org/3/library/time.html#time.strftime "(in Python v3.15)"). There isn’t an equivalent for the `'%U'` [`strftime()`](https://docs.python.org/3/library/time.html#time.strftime "(in Python v3.15)") format string in [`date`](../../templates/builtins/#std-templatefilter-date). Therefore, you should avoid using [`date`](../../templates/builtins/#std-templatefilter-date) to generate URLs for `WeekArchiveView`. ## `DayArchiveView`[¶](#dayarchiveview "Link to this heading") * *class *DayArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L628)[¶](#django.views.generic.dates.DayArchiveView "Link to this definition") A day archive page showing all objects in a given day. Days in the future throw a 404 error, regardless of whether any objects exist for future days, unless you set `allow_future` to `True`. **Ancestors (MRO)** * [`django.views.generic.list.MultipleObjectTemplateResponseMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectTemplateResponseMixin "django.views.generic.list.MultipleObjectTemplateResponseMixin") * [`django.views.generic.base.TemplateResponseMixin`](../mixins-simple/#django.views.generic.base.TemplateResponseMixin "django.views.generic.base.TemplateResponseMixin") * [`django.views.generic.dates.BaseDayArchiveView`](#django.views.generic.dates.BaseDayArchiveView "django.views.generic.dates.BaseDayArchiveView") * [`django.views.generic.dates.YearMixin`](../mixins-date-based/#django.views.generic.dates.YearMixin "django.views.generic.dates.YearMixin") * [`django.views.generic.dates.MonthMixin`](../mixins-date-based/#django.views.generic.dates.MonthMixin "django.views.generic.dates.MonthMixin") * [`django.views.generic.dates.DayMixin`](../mixins-date-based/#django.views.generic.dates.DayMixin "django.views.generic.dates.DayMixin") * [`django.views.generic.dates.BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView") * [`django.views.generic.list.MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") * [`django.views.generic.dates.DateMixin`](../mixins-date-based/#django.views.generic.dates.DateMixin "django.views.generic.dates.DateMixin") * [`django.views.generic.base.View`](../base/#django.views.generic.base.View "django.views.generic.base.View") **Context** In addition to the context provided by [`MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") (via [`BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView")), the template’s context will be: * `day`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the given day. * `next_day`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the next day, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). * `previous_day`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the previous day, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). * `next_month`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the next month, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). * `previous_month`: A [`date`](https://docs.python.org/3/library/datetime.html#datetime.date "(in Python v3.15)") object representing the first day of the previous month, according to [`allow_empty`](../mixins-date-based/#django.views.generic.dates.BaseDateListView.allow_empty "django.views.generic.dates.BaseDateListView.allow_empty") and [`allow_future`](../mixins-date-based/#django.views.generic.dates.DateMixin.allow_future "django.views.generic.dates.DateMixin.allow_future"). **Notes** * Uses a default `template_name_suffix` of `_archive_day`. **Example myapp/views.py**: ``` from django.views.generic.dates import DayArchiveView from myapp.models import Article class ArticleDayArchiveView(DayArchiveView): queryset = Article.objects.all() date_field = "pub_date" allow_future = True ``` **Example myapp/urls.py**: ``` from django.urls import path from myapp.views import ArticleDayArchiveView urlpatterns = [ # Example: /2012/nov/10/ path( "///", ArticleDayArchiveView.as_view(), name="archive_day", ), ] ``` **Example myapp/article\_archive\_day.html**: ```

{{ day }}

    {% for article in object_list %}
  • {{ article.pub_date|date:"F j, Y" }}: {{ article.title }}
    • {% endfor %}

{% if previous_day %} Previous Day: {{ previous_day }} {% endif %} {% if previous_day and next_day %}--{% endif %} {% if next_day %} Next Day: {{ next_day }} {% endif %}

``` ## `TodayArchiveView`[¶](#todayarchiveview "Link to this heading") * *class *TodayArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L646)[¶](#django.views.generic.dates.TodayArchiveView "Link to this definition") A day archive page showing all objects for *today*. This is exactly the same as [`django.views.generic.dates.DayArchiveView`](#django.views.generic.dates.DayArchiveView "django.views.generic.dates.DayArchiveView"), except today’s date is used instead of the `year`/`month`/`day` arguments. **Ancestors (MRO)** * [`django.views.generic.list.MultipleObjectTemplateResponseMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectTemplateResponseMixin "django.views.generic.list.MultipleObjectTemplateResponseMixin") * [`django.views.generic.base.TemplateResponseMixin`](../mixins-simple/#django.views.generic.base.TemplateResponseMixin "django.views.generic.base.TemplateResponseMixin") * [`django.views.generic.dates.BaseTodayArchiveView`](#django.views.generic.dates.BaseTodayArchiveView "django.views.generic.dates.BaseTodayArchiveView") * [`django.views.generic.dates.BaseDayArchiveView`](#django.views.generic.dates.BaseDayArchiveView "django.views.generic.dates.BaseDayArchiveView") * [`django.views.generic.dates.YearMixin`](../mixins-date-based/#django.views.generic.dates.YearMixin "django.views.generic.dates.YearMixin") * [`django.views.generic.dates.MonthMixin`](../mixins-date-based/#django.views.generic.dates.MonthMixin "django.views.generic.dates.MonthMixin") * [`django.views.generic.dates.DayMixin`](../mixins-date-based/#django.views.generic.dates.DayMixin "django.views.generic.dates.DayMixin") * [`django.views.generic.dates.BaseDateListView`](../mixins-date-based/#django.views.generic.dates.BaseDateListView "django.views.generic.dates.BaseDateListView") * [`django.views.generic.list.MultipleObjectMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin "django.views.generic.list.MultipleObjectMixin") * [`django.views.generic.dates.DateMixin`](../mixins-date-based/#django.views.generic.dates.DateMixin "django.views.generic.dates.DateMixin") * [`django.views.generic.base.View`](../base/#django.views.generic.base.View "django.views.generic.base.View") **Notes** * Uses a default `template_name_suffix` of `_archive_today`. **Example myapp/views.py**: ``` from django.views.generic.dates import TodayArchiveView from myapp.models import Article class ArticleTodayArchiveView(TodayArchiveView): queryset = Article.objects.all() date_field = "pub_date" allow_future = True ``` **Example myapp/urls.py**: ``` from django.urls import path from myapp.views import ArticleTodayArchiveView urlpatterns = [ path("today/", ArticleTodayArchiveView.as_view(), name="archive_today"), ] ``` Where is the example template for `TodayArchiveView`? This view uses by default the same template as the [`DayArchiveView`](../flattened-index/#DayArchiveView "DayArchiveView"), which is in the previous example. If you need a different template, set the `template_name` attribute to be the name of the new template. ## `DateDetailView`[¶](#datedetailview "Link to this heading") * *class *DateDetailView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L698)[¶](#django.views.generic.dates.DateDetailView "Link to this definition") A page representing an individual object. If the object has a date value in the future, the view will throw a 404 error by default, unless you set `allow_future` to `True`. **Ancestors (MRO)** * [`django.views.generic.detail.SingleObjectTemplateResponseMixin`](../mixins-single-object/#django.views.generic.detail.SingleObjectTemplateResponseMixin "django.views.generic.detail.SingleObjectTemplateResponseMixin") * [`django.views.generic.base.TemplateResponseMixin`](../mixins-simple/#django.views.generic.base.TemplateResponseMixin "django.views.generic.base.TemplateResponseMixin") * [`django.views.generic.dates.BaseDateDetailView`](#django.views.generic.dates.BaseDateDetailView "django.views.generic.dates.BaseDateDetailView") * [`django.views.generic.dates.YearMixin`](../mixins-date-based/#django.views.generic.dates.YearMixin "django.views.generic.dates.YearMixin") * [`django.views.generic.dates.MonthMixin`](../mixins-date-based/#django.views.generic.dates.MonthMixin "django.views.generic.dates.MonthMixin") * [`django.views.generic.dates.DayMixin`](../mixins-date-based/#django.views.generic.dates.DayMixin "django.views.generic.dates.DayMixin") * [`django.views.generic.dates.DateMixin`](../mixins-date-based/#django.views.generic.dates.DateMixin "django.views.generic.dates.DateMixin") * [`django.views.generic.detail.BaseDetailView`](../generic-display/#django.views.generic.detail.BaseDetailView "django.views.generic.detail.BaseDetailView") * [`django.views.generic.detail.SingleObjectMixin`](../mixins-single-object/#django.views.generic.detail.SingleObjectMixin "django.views.generic.detail.SingleObjectMixin") * [`django.views.generic.base.View`](../base/#django.views.generic.base.View "django.views.generic.base.View") **Context** * Includes the single object associated with the `model` specified in the `DateDetailView`. **Notes** * Uses a default `template_name_suffix` of `_detail`. **Example myapp/urls.py**: ``` from django.urls import path from django.views.generic.dates import DateDetailView urlpatterns = [ path( "////", DateDetailView.as_view(model=Article, date_field="pub_date"), name="archive_date_detail", ), ] ``` **Example myapp/article\_detail.html**: ```

{{ object.title }}

``` Note All of the generic views listed above have matching `Base` views that only differ in that they do not include the [`MultipleObjectTemplateResponseMixin`](../mixins-multiple-object/#django.views.generic.list.MultipleObjectTemplateResponseMixin "django.views.generic.list.MultipleObjectTemplateResponseMixin") (for the archive views) or [`SingleObjectTemplateResponseMixin`](../mixins-single-object/#django.views.generic.detail.SingleObjectTemplateResponseMixin "django.views.generic.detail.SingleObjectTemplateResponseMixin") (for the [`DateDetailView`](../flattened-index/#DateDetailView "DateDetailView")): * *class *BaseArchiveIndexView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L393)[¶](#django.views.generic.dates.BaseArchiveIndexView "Link to this definition") - *class *BaseYearArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L419)[¶](#django.views.generic.dates.BaseYearArchiveView "Link to this definition") * *class *BaseMonthArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L475)[¶](#django.views.generic.dates.BaseMonthArchiveView "Link to this definition") - *class *BaseWeekArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L521)[¶](#django.views.generic.dates.BaseWeekArchiveView "Link to this definition") * *class *BaseDayArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L583)[¶](#django.views.generic.dates.BaseDayArchiveView "Link to this definition") - *class *BaseTodayArchiveView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L634)[¶](#django.views.generic.dates.BaseTodayArchiveView "Link to this definition") * *class *BaseDateDetailView[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/generic/dates.py#L652)[¶](#django.views.generic.dates.BaseDateDetailView "Link to this definition") [**Back to Top](#top) ## Additional Information ### Support Django! * [Campus League of Puzzlers donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Generic date views](#) * [`ArchiveIndexView`](#archiveindexview) * [`YearArchiveView`](#yeararchiveview) * [`MonthArchiveView`](#montharchiveview) * [`WeekArchiveView`](#weekarchiveview) * [`DayArchiveView`](#dayarchiveview) * [`TodayArchiveView`](#todayarchiveview) * [`DateDetailView`](#datedetailview) ---- url: https://docs.djangoproject.com/en/6.1/ref/contrib/postgres/fields/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/postgres/fields/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/contrib/postgres/fields/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/contrib/postgres/fields/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/contrib/postgres/fields/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/contrib/postgres/fields/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/contrib/postgres/fields/) - [it](https://docs.djangoproject.com/it/6.1/ref/contrib/postgres/fields/) - [id](https://docs.djangoproject.com/id/6.1/ref/contrib/postgres/fields/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/contrib/postgres/fields/) - [es](https://docs.djangoproject.com/es/6.1/ref/contrib/postgres/fields/) - [el](https://docs.djangoproject.com/el/6.1/ref/contrib/postgres/fields/) * * [dev](https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/contrib/postgres/fields/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/contrib/postgres/fields/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/contrib/postgres/fields/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/contrib/postgres/fields/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/contrib/postgres/fields/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/contrib/postgres/fields/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/contrib/postgres/fields/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/contrib/postgres/fields/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/contrib/postgres/fields/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/fields/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/contrib/postgres/fields/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/contrib/postgres/fields/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/contrib/postgres/fields/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/contrib/postgres/fields/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/contrib/postgres/fields/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/contrib/postgres/fields/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/contrib/postgres/fields/) - [**](#top) # PostgreSQL specific model fields[¶](#postgresql-specific-model-fields "Link to this heading") All of these fields are available from the `django.contrib.postgres.fields` module. ## Indexing these fields[¶](#indexing-these-fields "Link to this heading") [`Index`](../../../models/indexes/#django.db.models.Index "django.db.models.Index") and [`Field.db_index`](../../../models/fields/#django.db.models.Field.db_index "django.db.models.Field.db_index") both create a B-tree index, which isn’t particularly helpful when querying complex data types. Indexes such as [`GinIndex`](../indexes/#django.contrib.postgres.indexes.GinIndex "django.contrib.postgres.indexes.GinIndex") and [`GistIndex`](../indexes/#django.contrib.postgres.indexes.GistIndex "django.contrib.postgres.indexes.GistIndex") are better suited, though the index choice is dependent on the queries that you’re using. Generally, GiST may be a good choice for the [range fields](#range-fields) and [`HStoreField`](#django.contrib.postgres.fields.HStoreField "django.contrib.postgres.fields.HStoreField"), and GIN may be helpful for [`ArrayField`](#django.contrib.postgres.fields.ArrayField "django.contrib.postgres.fields.ArrayField"). ## `ArrayField`[¶](#arrayfield "Link to this heading") * *class *ArrayField(*base\_field*, *size=None*, *\*\*options*)[¶](#django.contrib.postgres.fields.ArrayField "Link to this definition") A field for storing lists of data. Most field types can be used, and you pass another field instance as the [`base_field`](#django.contrib.postgres.fields.ArrayField.base_field "django.contrib.postgres.fields.ArrayField.base_field"). You may also specify a [`size`](#django.contrib.postgres.fields.ArrayField.size "django.contrib.postgres.fields.ArrayField.size"). `ArrayField` can be nested to store multi-dimensional arrays. If you give the field a [`default`](../../../models/fields/#django.db.models.Field.default "django.db.models.Field.default"), ensure it’s a callable such as `list` (for an empty default) or a callable that returns a list (such as a function). Incorrectly using `default=[]` creates a mutable default that is shared between all instances of `ArrayField`. * base\_field[¶](#django.contrib.postgres.fields.ArrayField.base_field "Link to this definition") This is a required argument. Specifies the underlying data type and behavior for the array. It should be an instance of a subclass of [`Field`](../../../models/fields/#django.db.models.Field "django.db.models.Field"). For example, it could be an [`IntegerField`](../../../models/fields/#django.db.models.IntegerField "django.db.models.IntegerField") or a [`CharField`](../../../models/fields/#django.db.models.CharField "django.db.models.CharField"). Most field types are permitted, with the exception of those handling relational data ([`ForeignKey`](../../../models/fields/#django.db.models.ForeignKey "django.db.models.ForeignKey"), [`OneToOneField`](../../../models/fields/#django.db.models.OneToOneField "django.db.models.OneToOneField") and [`ManyToManyField`](../../../models/fields/#django.db.models.ManyToManyField "django.db.models.ManyToManyField")) and file fields ([`FileField`](../../../models/fields/#django.db.models.FileField "django.db.models.FileField") and [`ImageField`](../../../models/fields/#django.db.models.ImageField "django.db.models.ImageField")). It is possible to nest array fields - you can specify an instance of `ArrayField` as the `base_field`. For example: ``` from django.contrib.postgres.fields import ArrayField from django.db import models class ChessBoard(models.Model): board = ArrayField( ArrayField( models.CharField(max_length=10, blank=True), size=8, ), size=8, ) ``` Transformation of values between the database and the model, validation of data and configuration, and serialization are all delegated to the underlying base field. - size[¶](#django.contrib.postgres.fields.ArrayField.size "Link to this definition") This is an optional argument. If passed, the array will have a maximum size as specified. This will be passed to the database, although PostgreSQL at present does not enforce the restriction. Note When nesting `ArrayField`, whether you use the `size` parameter or not, PostgreSQL requires that the arrays are rectangular: ``` from django.contrib.postgres.fields import ArrayField from django.db import models class Board(models.Model): pieces = ArrayField(ArrayField(models.IntegerField())) # Valid Board( pieces=[ [2, 3], [2, 1], ] ) # Not valid Board( pieces=[ [2, 3], [2], ] ) ``` If irregular shapes are required, then the underlying field should be made nullable and the values padded with `None`. ### Querying `ArrayField`[¶](#querying-arrayfield "Link to this heading") There are a number of custom lookups and transforms for [`ArrayField`](#django.contrib.postgres.fields.ArrayField "django.contrib.postgres.fields.ArrayField"). We will use the following example model: ``` from django.contrib.postgres.fields import ArrayField from django.db import models class Post(models.Model): name = models.CharField(max_length=200) tags = ArrayField(models.CharField(max_length=200), blank=True) def __str__(self): return self.name ``` #### `contains`[¶](#contains "Link to this heading") The [`contains`](../../../models/querysets/#std-fieldlookup-contains) lookup is overridden on [`ArrayField`](#django.contrib.postgres.fields.ArrayField "django.contrib.postgres.fields.ArrayField"). The returned objects will be those where the values passed are a subset of the data. It uses the SQL operator `@>`. For example: ``` >>> Post.objects.create(name="First post", tags=["thoughts", "django"]) >>> Post.objects.create(name="Second post", tags=["thoughts"]) >>> Post.objects.create(name="Third post", tags=["tutorial", "django"]) >>> Post.objects.filter(tags__contains=["thoughts"]) , ]> >>> Post.objects.filter(tags__contains=["django"]) , ]> >>> Post.objects.filter(tags__contains=["django", "thoughts"]) ]> ``` #### `contained_by`[¶](#contained-by "Link to this heading") This is the inverse of the [`contains`](#std-fieldlookup-arrayfield.contains) lookup - the objects returned will be those where the data is a subset of the values passed. It uses the SQL operator `<@`. For example: ``` >>> Post.objects.create(name="First post", tags=["thoughts", "django"]) >>> Post.objects.create(name="Second post", tags=["thoughts"]) >>> Post.objects.create(name="Third post", tags=["tutorial", "django"]) >>> Post.objects.filter(tags__contained_by=["thoughts", "django"]) , ]> >>> Post.objects.filter(tags__contained_by=["thoughts", "django", "tutorial"]) , , ]> ``` #### `overlap`[¶](#overlap "Link to this heading") Returns objects where the data shares any results with the values passed. Uses the SQL operator `&&`. For example: ``` >>> Post.objects.create(name="First post", tags=["thoughts", "django"]) >>> Post.objects.create(name="Second post", tags=["thoughts", "tutorial"]) >>> Post.objects.create(name="Third post", tags=["tutorial", "django"]) >>> Post.objects.filter(tags__overlap=["thoughts"]) , ]> >>> Post.objects.filter(tags__overlap=["thoughts", "tutorial"]) , , ]> >>> Post.objects.filter(tags__overlap=Post.objects.values_list("tags")) , , ]> ``` #### `len`[¶](#len "Link to this heading") Returns the length of the array. The lookups available afterward are those available for [`IntegerField`](../../../models/fields/#django.db.models.IntegerField "django.db.models.IntegerField"). For example: ``` >>> Post.objects.create(name="First post", tags=["thoughts", "django"]) >>> Post.objects.create(name="Second post", tags=["thoughts"]) >>> Post.objects.filter(tags__len=1) ]> ``` #### Index transforms[¶](#index-transforms "Link to this heading") Index transforms index into the array. Any non-negative integer can be used. There are no errors if it exceeds the [`size`](#django.contrib.postgres.fields.ArrayField.size "django.contrib.postgres.fields.ArrayField.size") of the array. The lookups available after the transform are those from the [`base_field`](#django.contrib.postgres.fields.ArrayField.base_field "django.contrib.postgres.fields.ArrayField.base_field"). For example: ``` >>> Post.objects.create(name="First post", tags=["thoughts", "django"]) >>> Post.objects.create(name="Second post", tags=["thoughts"]) >>> Post.objects.filter(tags__0="thoughts") , ]> >>> Post.objects.filter(tags__1__iexact="Django") ]> >>> Post.objects.filter(tags__276="javascript") ``` Note PostgreSQL uses 1-based indexing for array fields when writing raw SQL. However these indexes and those used in [`slices`](#std-fieldlookup-arrayfield.slice) use 0-based indexing to be consistent with Python. #### Slice transforms[¶](#slice-transforms "Link to this heading") Slice transforms take a slice of the array. Any two non-negative integers can be used, separated by a single underscore. The lookups available after the transform do not change. For example: ``` >>> Post.objects.create(name="First post", tags=["thoughts", "django"]) >>> Post.objects.create(name="Second post", tags=["thoughts"]) >>> Post.objects.create(name="Third post", tags=["django", "python", "thoughts"]) >>> Post.objects.filter(tags__0_1=["thoughts"]) , ]> >>> Post.objects.filter(tags__0_2__contains=["thoughts"]) , ]> ``` Note PostgreSQL uses 1-based indexing for array fields when writing raw SQL. However these slices and those used in [`indexes`](#std-fieldlookup-arrayfield.index) use 0-based indexing to be consistent with Python. Multidimensional arrays with indexes and slices PostgreSQL has some rather esoteric behavior when using indexes and slices on multidimensional arrays. It will always work to use indexes to reach down to the final underlying data, but most other slices behave strangely at the database level and cannot be supported in a logical, consistent fashion by Django. ## `HStoreField`[¶](#hstorefield "Link to this heading") * *class *HStoreField(*\*\*options*)[¶](#django.contrib.postgres.fields.HStoreField "Link to this definition") A field for storing key-value pairs. The Python data type used is a `dict`. Keys must be strings, and values may be either strings or nulls (`None` in Python). To use this field, you’ll need to: 1. Add `'django.contrib.postgres'` in your [`INSTALLED_APPS`](../../../settings/#std-setting-INSTALLED_APPS). 2. [Set up the hstore extension](../operations/#create-postgresql-extensions) in PostgreSQL. You’ll see an error like `can't adapt type 'dict'` if you skip the first step, or `type "hstore" does not exist` if you skip the second. Note On occasions it may be useful to require or restrict the keys which are valid for a given field. This can be done using the [`KeysValidator`](../validators/#django.contrib.postgres.validators.KeysValidator "django.contrib.postgres.validators.KeysValidator"). ### Querying `HStoreField`[¶](#querying-hstorefield "Link to this heading") In addition to the ability to query by key, there are a number of custom lookups available for `HStoreField`. We will use the following example model: ``` from django.contrib.postgres.fields import HStoreField from django.db import models class Dog(models.Model): name = models.CharField(max_length=200) data = HStoreField() def __str__(self): return self.name ``` #### Key lookups[¶](#key-lookups "Link to this heading") To query based on a given key, you can use that key as the lookup name: ``` >>> Dog.objects.create(name="Rufus", data={"breed": "labrador"}) >>> Dog.objects.create(name="Meg", data={"breed": "collie"}) >>> Dog.objects.filter(data__breed="collie") ]> ``` You can chain other lookups after key lookups: ``` >>> Dog.objects.filter(data__breed__contains="l") , ]> ``` or use `F()` expressions to annotate a key value. For example: ``` >>> from django.db.models import F >>> rufus = Dog.objects.annotate(breed=F("data__breed"))[0] >>> rufus.breed 'labrador' ``` If the key you wish to query by clashes with the name of another lookup, you need to use the [`hstorefield.contains`](#std-fieldlookup-hstorefield.contains) lookup instead. Note Key transforms can also be chained with: [`contains`](../../../models/querysets/#std-fieldlookup-contains), [`icontains`](../../../models/querysets/#std-fieldlookup-icontains), [`endswith`](../../../models/querysets/#std-fieldlookup-endswith), [`iendswith`](../../../models/querysets/#std-fieldlookup-iendswith), [`iexact`](../../../models/querysets/#std-fieldlookup-iexact), [`regex`](../../../models/querysets/#std-fieldlookup-regex), [`iregex`](../../../models/querysets/#std-fieldlookup-iregex), [`startswith`](../../../models/querysets/#std-fieldlookup-startswith), and [`istartswith`](../../../models/querysets/#std-fieldlookup-istartswith) lookups. Warning Since any string could be a key in a hstore value, any lookup other than those listed below will be interpreted as a key lookup. No errors are raised. Be extra careful for typing mistakes, and always check your queries work as you intend. #### `contains`[¶](#std-fieldlookup-hstorefield.contains "Link to this heading") The [`contains`](../../../models/querysets/#std-fieldlookup-contains) lookup is overridden on [`HStoreField`](#django.contrib.postgres.fields.HStoreField "django.contrib.postgres.fields.HStoreField"). The returned objects are those where the given `dict` of key-value pairs are all contained in the field. It uses the SQL operator `@>`. For example: ``` >>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"}) >>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"}) >>> Dog.objects.create(name="Fred", data={}) >>> Dog.objects.filter(data__contains={"owner": "Bob"}) , ]> >>> Dog.objects.filter(data__contains={"breed": "collie"}) ]> ``` #### `contained_by`[¶](#std-fieldlookup-hstorefield.contained_by "Link to this heading") This is the inverse of the [`contains`](#std-fieldlookup-hstorefield.contains) lookup - the objects returned will be those where the key-value pairs on the object are a subset of those in the value passed. It uses the SQL operator `<@`. For example: ``` >>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"}) >>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"}) >>> Dog.objects.create(name="Fred", data={}) >>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"}) , ]> >>> Dog.objects.filter(data__contained_by={"breed": "collie"}) ]> ``` #### `has_key`[¶](#has-key "Link to this heading") Returns objects where the given key is in the data. Uses the SQL operator `?`. For example: ``` >>> Dog.objects.create(name="Rufus", data={"breed": "labrador"}) >>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"}) >>> Dog.objects.filter(data__has_key="owner") ]> ``` #### `has_any_keys`[¶](#has-any-keys "Link to this heading") Returns objects where any of the given keys are in the data. Uses the SQL operator `?|`. For example: ``` >>> Dog.objects.create(name="Rufus", data={"breed": "labrador"}) >>> Dog.objects.create(name="Meg", data={"owner": "Bob"}) >>> Dog.objects.create(name="Fred", data={}) >>> Dog.objects.filter(data__has_any_keys=["owner", "breed"]) , ]> ``` #### `has_keys`[¶](#has-keys "Link to this heading") Returns objects where all of the given keys are in the data. Uses the SQL operator `?&`. For example: ``` >>> Dog.objects.create(name="Rufus", data={}) >>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"}) >>> Dog.objects.filter(data__has_keys=["breed", "owner"]) ]> ``` #### `keys`[¶](#keys "Link to this heading") Returns objects where the array of keys is the given value. Note that the order is not guaranteed to be reliable, so this transform is mainly useful for using in conjunction with lookups on [`ArrayField`](#django.contrib.postgres.fields.ArrayField "django.contrib.postgres.fields.ArrayField"). Uses the SQL function `akeys()`. For example: ``` >>> Dog.objects.create(name="Rufus", data={"toy": "bone"}) >>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"}) >>> Dog.objects.filter(data__keys__overlap=["breed", "toy"]) , ]> ``` #### `values`[¶](#values "Link to this heading") Returns objects where the array of values is the given value. Note that the order is not guaranteed to be reliable, so this transform is mainly useful for using in conjunction with lookups on [`ArrayField`](#django.contrib.postgres.fields.ArrayField "django.contrib.postgres.fields.ArrayField"). Uses the SQL function `avals()`. For example: ``` >>> Dog.objects.create(name="Rufus", data={"breed": "labrador"}) >>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"}) >>> Dog.objects.filter(data__values__contains=["collie"]) ]> ``` ## Range Fields[¶](#range-fields "Link to this heading") There are five range field types, corresponding to the built-in range types in PostgreSQL. These fields are used to store a range of values; for example the start and end timestamps of an event, or the range of ages an activity is suitable for. All of the range fields translate to [psycopg Range objects](https://www.psycopg.org/psycopg3/docs/basic/pgtypes.html#adapt-range "(in psycopg)") in Python, but also accept tuples as input if no bounds information is necessary. The default is lower bound included, upper bound excluded, that is `[)` (see the PostgreSQL documentation for details about [different bounds](https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-IO)). The default bounds can be changed for non-discrete range fields ([`DateTimeRangeField`](#django.contrib.postgres.fields.DateTimeRangeField "django.contrib.postgres.fields.DateTimeRangeField") and [`DecimalRangeField`](#django.contrib.postgres.fields.DecimalRangeField "django.contrib.postgres.fields.DecimalRangeField")) by using the `default_bounds` argument. PostgreSQL normalizes a range with no points to the empty range A range with equal values specified for an included lower bound and an excluded upper bound, such as `Range(datetime.date(2005, 6, 21), datetime.date(2005, 6, 21))` or `[4, 4)`, has no points. PostgreSQL will normalize the value to empty when saving to the database, and the original bound values will be lost. See the [PostgreSQL documentation for details](https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-IO). ### `IntegerRangeField`[¶](#integerrangefield "Link to this heading") * *class *IntegerRangeField(*\*\*options*)[¶](#django.contrib.postgres.fields.IntegerRangeField "Link to this definition") Stores a range of integers. Based on an [`IntegerField`](../../../models/fields/#django.db.models.IntegerField "django.db.models.IntegerField"). Represented by an `int4range` in the database and a `django.db.backends.postgresql.psycopg_any.NumericRange` in Python. Regardless of the bounds specified when saving the data, PostgreSQL always returns a range in a canonical form that includes the lower bound and excludes the upper bound, that is `[)`. ### `BigIntegerRangeField`[¶](#bigintegerrangefield "Link to this heading") * *class *BigIntegerRangeField(*\*\*options*)[¶](#django.contrib.postgres.fields.BigIntegerRangeField "Link to this definition") Stores a range of large integers. Based on a [`BigIntegerField`](../../../models/fields/#django.db.models.BigIntegerField "django.db.models.BigIntegerField"). Represented by an `int8range` in the database and a `django.db.backends.postgresql.psycopg_any.NumericRange` in Python. Regardless of the bounds specified when saving the data, PostgreSQL always returns a range in a canonical form that includes the lower bound and excludes the upper bound, that is `[)`. ### `DecimalRangeField`[¶](#decimalrangefield "Link to this heading") * *class *DecimalRangeField(*default\_bounds='\[)'*, *\*\*options*)[¶](#django.contrib.postgres.fields.DecimalRangeField "Link to this definition") Stores a range of floating point values. Based on a [`DecimalField`](../../../models/fields/#django.db.models.DecimalField "django.db.models.DecimalField"). Represented by a `numrange` in the database and a `django.db.backends.postgresql.psycopg_any.NumericRange` in Python. * default\_bounds[¶](#django.contrib.postgres.fields.DecimalRangeField.default_bounds "Link to this definition") Optional. The value of `bounds` for list and tuple inputs. The default is lower bound included, upper bound excluded, that is `[)` (see the PostgreSQL documentation for details about [different bounds](https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-IO)). `default_bounds` is not used for `django.db.backends.postgresql.psycopg_any.NumericRange` inputs. ### `DateTimeRangeField`[¶](#datetimerangefield "Link to this heading") * *class *DateTimeRangeField(*default\_bounds='\[)'*, *\*\*options*)[¶](#django.contrib.postgres.fields.DateTimeRangeField "Link to this definition") Stores a range of timestamps. Based on a [`DateTimeField`](../../../models/fields/#django.db.models.DateTimeField "django.db.models.DateTimeField"). Represented by a `tstzrange` in the database and a `django.db.backends.postgresql.psycopg_any.DateTimeTZRange` in Python. * default\_bounds[¶](#django.contrib.postgres.fields.DateTimeRangeField.default_bounds "Link to this definition") Optional. The value of `bounds` for list and tuple inputs. The default is lower bound included, upper bound excluded, that is `[)` (see the PostgreSQL documentation for details about [different bounds](https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-IO)). `default_bounds` is not used for `django.db.backends.postgresql.psycopg_any.DateTimeTZRange` inputs. ### `DateRangeField`[¶](#daterangefield "Link to this heading") * *class *DateRangeField(*\*\*options*)[¶](#django.contrib.postgres.fields.DateRangeField "Link to this definition") Stores a range of dates. Based on a [`DateField`](../../../models/fields/#django.db.models.DateField "django.db.models.DateField"). Represented by a `daterange` in the database and a `django.db.backends.postgresql.psycopg_any.DateRange` in Python. Regardless of the bounds specified when saving the data, PostgreSQL always returns a range in a canonical form that includes the lower bound and excludes the upper bound, that is `[)`. ### Querying Range Fields[¶](#querying-range-fields "Link to this heading") There are a number of custom lookups and transforms for range fields. They are available on all the above fields, but we will use the following example model: ``` from django.contrib.postgres.fields import IntegerRangeField from django.db import models class Event(models.Model): name = models.CharField(max_length=200) ages = IntegerRangeField() start = models.DateTimeField() def __str__(self): return self.name ``` We will also use the following example objects: ``` >>> import datetime >>> from django.utils import timezone >>> now = timezone.now() >>> Event.objects.create(name="Soft play", ages=(0, 10), start=now) >>> Event.objects.create( ... name="Pub trip", ages=(21, None), start=now - datetime.timedelta(days=1) ... ) ``` and `NumericRange`: ``` >>> from django.db.backends.postgresql.psycopg_any import NumericRange ``` #### Containment functions[¶](#containment-functions "Link to this heading") As with other PostgreSQL fields, there are three standard containment operators: `contains`, `contained_by` and `overlap`, using the SQL operators `@>`, `<@`, and `&&` respectively. ##### `contains`[¶](#std-fieldlookup-rangefield.contains "Link to this heading") ``` >>> Event.objects.filter(ages__contains=NumericRange(4, 5)) ]> ``` ##### `contained_by`[¶](#std-fieldlookup-rangefield.contained_by "Link to this heading") ``` >>> Event.objects.filter(ages__contained_by=NumericRange(0, 15)) ]> ``` The `contained_by` lookup is also available on the non-range field types: [`SmallAutoField`](../../../models/fields/#django.db.models.SmallAutoField "django.db.models.SmallAutoField"), [`AutoField`](../../../models/fields/#django.db.models.AutoField "django.db.models.AutoField"), [`BigAutoField`](../../../models/fields/#django.db.models.BigAutoField "django.db.models.BigAutoField"), [`SmallIntegerField`](../../../models/fields/#django.db.models.SmallIntegerField "django.db.models.SmallIntegerField"), [`IntegerField`](../../../models/fields/#django.db.models.IntegerField "django.db.models.IntegerField"), [`BigIntegerField`](../../../models/fields/#django.db.models.BigIntegerField "django.db.models.BigIntegerField"), [`DecimalField`](../../../models/fields/#django.db.models.DecimalField "django.db.models.DecimalField"), [`FloatField`](../../../models/fields/#django.db.models.FloatField "django.db.models.FloatField"), [`DateField`](../../../models/fields/#django.db.models.DateField "django.db.models.DateField"), and [`DateTimeField`](../../../models/fields/#django.db.models.DateTimeField "django.db.models.DateTimeField"). For example: ``` >>> from django.db.backends.postgresql.psycopg_any import DateTimeTZRange >>> Event.objects.filter( ... start__contained_by=DateTimeTZRange( ... timezone.now() - datetime.timedelta(hours=1), ... timezone.now() + datetime.timedelta(hours=1), ... ), ... ) ]> ``` ##### `overlap`[¶](#std-fieldlookup-rangefield.overlap "Link to this heading") ``` >>> Event.objects.filter(ages__overlap=NumericRange(8, 12)) ]> ``` #### Comparison functions[¶](#comparison-functions "Link to this heading") Range fields support the standard lookups: [`lt`](../../../models/querysets/#std-fieldlookup-lt), [`gt`](../../../models/querysets/#std-fieldlookup-gt), [`lte`](../../../models/querysets/#std-fieldlookup-lte) and [`gte`](../../../models/querysets/#std-fieldlookup-gte). These are not particularly helpful - they compare the lower bounds first and then the upper bounds only if necessary. This is also the strategy used to order by a range field. It is better to use the specific range comparison operators. ##### `fully_lt`[¶](#fully-lt "Link to this heading") The returned ranges are strictly less than the passed range. In other words, all the points in the returned range are less than all those in the passed range. ``` >>> Event.objects.filter(ages__fully_lt=NumericRange(11, 15)) ]> ``` ##### `fully_gt`[¶](#fully-gt "Link to this heading") The returned ranges are strictly greater than the passed range. In other words, the all the points in the returned range are greater than all those in the passed range. ``` >>> Event.objects.filter(ages__fully_gt=NumericRange(11, 15)) ]> ``` ##### `not_lt`[¶](#not-lt "Link to this heading") The returned ranges do not contain any points less than the passed range, that is the lower bound of the returned range is at least the lower bound of the passed range. ``` >>> Event.objects.filter(ages__not_lt=NumericRange(0, 15)) , ]> ``` ##### `not_gt`[¶](#not-gt "Link to this heading") The returned ranges do not contain any points greater than the passed range, that is the upper bound of the returned range is at most the upper bound of the passed range. ``` >>> Event.objects.filter(ages__not_gt=NumericRange(3, 10)) ]> ``` ##### `adjacent_to`[¶](#adjacent-to "Link to this heading") The returned ranges share a bound with the passed range. ``` >>> Event.objects.filter(ages__adjacent_to=NumericRange(10, 21)) , ]> ``` #### Querying using the bounds[¶](#querying-using-the-bounds "Link to this heading") Range fields support several extra lookups. ##### `startswith`[¶](#startswith "Link to this heading") Returned objects have the given lower bound. Can be chained to valid lookups for the base field. ``` >>> Event.objects.filter(ages__startswith=21) ]> ``` ##### `endswith`[¶](#endswith "Link to this heading") Returned objects have the given upper bound. Can be chained to valid lookups for the base field. ``` >>> Event.objects.filter(ages__endswith=10) ]> ``` ##### `isempty`[¶](#isempty "Link to this heading") Returned objects are empty ranges. Can be chained to valid lookups for a [`BooleanField`](../../../models/fields/#django.db.models.BooleanField "django.db.models.BooleanField"). ``` >>> Event.objects.filter(ages__isempty=True) ``` ##### `lower_inc`[¶](#lower-inc "Link to this heading") Returns objects that have inclusive or exclusive lower bounds, depending on the boolean value passed. Can be chained to valid lookups for a [`BooleanField`](../../../models/fields/#django.db.models.BooleanField "django.db.models.BooleanField"). ``` >>> Event.objects.filter(ages__lower_inc=True) , ]> ``` ##### `lower_inf`[¶](#lower-inf "Link to this heading") Returns objects that have unbounded (infinite) or bounded lower bound, depending on the boolean value passed. Can be chained to valid lookups for a [`BooleanField`](../../../models/fields/#django.db.models.BooleanField "django.db.models.BooleanField"). ``` >>> Event.objects.filter(ages__lower_inf=True) ``` ##### `upper_inc`[¶](#upper-inc "Link to this heading") Returns objects that have inclusive or exclusive upper bounds, depending on the boolean value passed. Can be chained to valid lookups for a [`BooleanField`](../../../models/fields/#django.db.models.BooleanField "django.db.models.BooleanField"). ``` >>> Event.objects.filter(ages__upper_inc=True) ``` ##### `upper_inf`[¶](#upper-inf "Link to this heading") Returns objects that have unbounded (infinite) or bounded upper bound, depending on the boolean value passed. Can be chained to valid lookups for a [`BooleanField`](../../../models/fields/#django.db.models.BooleanField "django.db.models.BooleanField"). ``` >>> Event.objects.filter(ages__upper_inf=True) ]> ``` ### Defining your own range types[¶](#defining-your-own-range-types "Link to this heading") PostgreSQL allows the definition of custom range types. Django’s model and form field implementations use base classes below, and `psycopg` provides a [`register_range()`](https://www.psycopg.org/psycopg3/docs/basic/pgtypes.html#psycopg.types.range.register_range "(in psycopg)") to allow use of custom range types. * *class *RangeField(*\*\*options*)[¶](#django.contrib.postgres.fields.RangeField "Link to this definition") Base class for model range fields. * base\_field[¶](#django.contrib.postgres.fields.RangeField.base_field "Link to this definition") The model field class to use. - range\_type[¶](#django.contrib.postgres.fields.RangeField.range_type "Link to this definition") The range type to use. * form\_field[¶](#django.contrib.postgres.fields.RangeField.form_field "Link to this definition") The form field class to use. Should be a subclass of [`django.contrib.postgres.forms.BaseRangeField`](#django.contrib.postgres.fields.django.contrib.postgres.forms.BaseRangeField "django.contrib.postgres.fields.django.contrib.postgres.forms.BaseRangeField"). - *class *django.contrib.postgres.forms.BaseRangeField[¶](#django.contrib.postgres.fields.django.contrib.postgres.forms.BaseRangeField "Link to this definition") Base class for form range fields. * base\_field[¶](#django.contrib.postgres.fields.django.contrib.postgres.forms.BaseRangeField.base_field "Link to this definition") The form field to use. - range\_type[¶](#django.contrib.postgres.fields.django.contrib.postgres.forms.BaseRangeField.range_type "Link to this definition") The range type to use. ### Range operators[¶](#range-operators "Link to this heading") * *class *RangeOperators[¶](#django.contrib.postgres.fields.RangeOperators "Link to this definition") PostgreSQL provides a set of SQL operators that can be used together with the range data types (see [the PostgreSQL documentation for the full details of range operators](https://www.postgresql.org/docs/current/functions-range.html#RANGE-OPERATORS-TABLE)). This class is meant as a convenient method to avoid typos. The operator names overlap with the names of corresponding lookups. ``` class RangeOperators: EQUAL = "=" NOT_EQUAL = "<>" CONTAINS = "@>" CONTAINED_BY = "<@" OVERLAPS = "&&" FULLY_LT = "<<" FULLY_GT = ">>" NOT_LT = "&>" NOT_GT = "&<" ADJACENT_TO = "-|-" ``` ### RangeBoundary() expressions[¶](#rangeboundary-expressions "Link to this heading") * *class *RangeBoundary(*inclusive\_lower=True*, *inclusive\_upper=False*)[¶](#django.contrib.postgres.fields.RangeBoundary "Link to this definition") * inclusive\_lower[¶](#django.contrib.postgres.fields.RangeBoundary.inclusive_lower "Link to this definition") If `True` (default), the lower bound is inclusive `'['`, otherwise it’s exclusive `'('`. - inclusive\_upper[¶](#django.contrib.postgres.fields.RangeBoundary.inclusive_upper "Link to this definition") If `False` (default), the upper bound is exclusive `')'`, otherwise it’s inclusive `']'`. A `RangeBoundary()` expression represents the range boundaries. It can be used with a custom range functions that expected boundaries, for example to define [`ExclusionConstraint`](../constraints/#django.contrib.postgres.constraints.ExclusionConstraint "django.contrib.postgres.constraints.ExclusionConstraint"). See [the PostgreSQL documentation for the full details](https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-INCLUSIVITY). [**Back to Top](#top) ## Additional Information ### Support Django! * [Experius donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [PostgreSQL specific model fields](#) * [Indexing these fields](#indexing-these-fields) * [`ArrayField`](#arrayfield) * [Querying `ArrayField`](#querying-arrayfield) * [`contains`](#contains) * [`contained_by`](#contained-by) * [`overlap`](#overlap) * [`len`](#len) * [Index transforms](#index-transforms) * [Slice transforms](#slice-transforms) * [`HStoreField`](#hstorefield) * [Querying `HStoreField`](#querying-hstorefield) * [Key lookups](#key-lookups) * [`contains`](#std-fieldlookup-hstorefield.contains) * [`contained_by`](#std-fieldlookup-hstorefield.contained_by) * [`has_key`](#has-key) * [`has_any_keys`](#has-any-keys) * [`has_keys`](#has-keys) * [`keys`](#keys) * [`values`](#values) * [Range Fields](#range-fields) * [`IntegerRangeField`](#integerrangefield) * [`BigIntegerRangeField`](#bigintegerrangefield) * [`DecimalRangeField`](#decimalrangefield) * [`DateTimeRangeField`](#datetimerangefield) * [`DateRangeField`](#daterangefield) * [Querying Range Fields](#querying-range-fields) * [Containment functions](#containment-functions) * [`contains`](#std-fieldlookup-rangefield.contains) * [`contained_by`](#std-fieldlookup-rangefield.contained_by) * [`overlap`](#std-fieldlookup-rangefield.overlap) * [Comparison functions](#comparison-functions) * [`fully_lt`](#fully-lt) * [`fully_gt`](#fully-gt) * [`not_lt`](#not-lt) * [`not_gt`](#not-gt) * [`adjacent_to`](#adjacent-to) * [Querying using the bounds](#querying-using-the-bounds) * [`startswith`](#startswith) * [`endswith`](#endswith) * [`isempty`](#isempty) * [`lower_inc`](#lower-inc) * [`lower_inf`](#lower-inf) * [`upper_inc`](#upper-inc) * [`upper_inf`](#upper-inf) * [Defining your own range types](#defining-your-own-range-types) * [Range operators](#range-operators) * [RangeBoundary() expressions](#rangeboundary-expressions) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.4.8/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.4.8/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.4.8/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.4.8/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.4.8/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.4.8/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.4.8/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.4.8/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.4.8/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.4.8/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.4.8/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.4.8/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.4.8/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.4.8/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.4.8/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.4.8/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.4.8/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.4.8/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.4.8/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.4.8/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.4.8/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.4.8/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.4.8/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.4.8/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.4.8/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.4.8/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.4.8/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.4.8/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.4.8/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.4.8/) - [**](#top) # Django 1.4.8 release notes[¶](#django-1-4-8-release-notes "Link to this heading") *September 14, 2013* Django 1.4.8 fixes two security issues present in previous Django releases in the 1.4 series. ## Denial-of-service via password hashers[¶](#denial-of-service-via-password-hashers "Link to this heading") In previous versions of Django, no limit was imposed on the plaintext length of a password. This allowed a denial-of-service attack through submission of bogus but extremely large passwords, tying up server resources performing the (expensive, and increasingly expensive with the length of the password) calculation of the corresponding hash. As of 1.4.8, Django’s authentication framework imposes a 4096-byte limit on passwords and will fail authentication with any submitted password of greater length. ## Corrected usage of [`sensitive_post_parameters()`](../../howto/error-reporting/#django.views.decorators.debug.sensitive_post_parameters "django.views.decorators.debug.sensitive_post_parameters") in [`django.contrib.auth`](../../topics/auth/#module-django.contrib.auth "django.contrib.auth: Django's authentication framework.")’s admin[¶](#corrected-usage-of-sensitive-post-parameters-in-django-contrib-auths-admin "Link to this heading") The decoration of the `add_view` and `user_change_password` user admin views with [`sensitive_post_parameters()`](../../howto/error-reporting/#django.views.decorators.debug.sensitive_post_parameters "django.views.decorators.debug.sensitive_post_parameters") did not include [`method_decorator()`](../../ref/utils/#django.utils.decorators.method_decorator "django.utils.decorators.method_decorator") (required since the views are methods) resulting in the decorator not being properly applied. This usage has been fixed and [`sensitive_post_parameters()`](../../howto/error-reporting/#django.views.decorators.debug.sensitive_post_parameters "django.views.decorators.debug.sensitive_post_parameters") will now throw an exception if it’s improperly used. [**Back to Top](#top) ## Additional Information ### Support Django! * [Fako Berkers donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.4.8 release notes](#) * [Denial-of-service via password hashers](#denial-of-service-via-password-hashers) * [Corrected usage of `sensitive_post_parameters()` in `django.contrib.auth`’s admin](#corrected-usage-of-sensitive-post-parameters-in-django-contrib-auths-admin) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.2.1/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.2.1/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.2.1/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.2.1/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.2.1/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.2.1/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.2.1/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.2.1/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.2.1/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.2.1/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.2.1/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.2.1/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.2.1/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.2.1/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.2.1/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.2.1/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.2.1/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.2.1/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.2.1/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.2.1/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.2.1/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.2.1/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.2.1/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.2.1/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.2.1/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.2.1/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.2.1/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.2.1/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.2.1/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.2.1/) - [**](#top) # Django 1.2.1 release notes[¶](#django-1-2-1-release-notes "Link to this heading") Django 1.2.1 was released almost immediately after 1.2.0 to correct two small bugs: one was in the documentation packaging script, the other was a [bug](https://code.djangoproject.com/ticket/13560) that affected datetime form field widgets when localization was enabled. [**Back to Top](#top) ## Additional Information ### Support Django! * [Djangowaves donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.2.1 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.4.6/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.4.6/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.4.6/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.4.6/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.4.6/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.4.6/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.4.6/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.4.6/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.4.6/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.4.6/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.4.6/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.4.6/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.4.6/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.4.6/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.4.6/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.4.6/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.4.6/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.4.6/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.4.6/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.4.6/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.4.6/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.4.6/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.4.6/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.4.6/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.4.6/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.4.6/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.4.6/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.4.6/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.4.6/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.4.6/) - [**](#top) # Django 1.4.6 release notes[¶](#django-1-4-6-release-notes "Link to this heading") *August 13, 2013* Django 1.4.6 fixes one security issue present in previous Django releases in the 1.4 series, as well as one other bug. This is the sixth bugfix/security release in the Django 1.4 series. ## Mitigated possible XSS attack via user-supplied redirect URLs[¶](#mitigated-possible-xss-attack-via-user-supplied-redirect-urls "Link to this heading") Django relies on user input in some cases (e.g. `django.contrib.auth.views.login()`, `django.contrib.comments`, and [i18n](../../topics/i18n/)) to redirect the user to an “on success” URL. The security checks for these redirects (namely `django.utils.http.is_safe_url()`) didn’t check if the scheme is `http(s)` and as such allowed `javascript:...` URLs to be entered. If a developer relied on `is_safe_url()` to provide safe redirect targets and put such a URL into a link, they could suffer from a XSS attack. This bug doesn’t affect Django currently, since we only put this URL into the `Location` response header and browsers seem to ignore JavaScript there. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed an obscure bug with the [`override_settings()`](../../topics/testing/tools/#django.test.override_settings "django.test.override_settings") decorator. If you hit an `AttributeError: 'Settings' object has no attribute '_original_allowed_hosts'` exception, it’s probably fixed (#20636). [**Back to Top](#top) ## Additional Information ### Support Django! * [Tiwaz donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.4.6 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/5.1.13/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/5.1.13/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/5.1.13/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/5.1.13/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/5.1.13/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/5.1.13/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/5.1.13/) - [it](https://docs.djangoproject.com/it/6.1/releases/5.1.13/) - [id](https://docs.djangoproject.com/id/6.1/releases/5.1.13/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/5.1.13/) - [es](https://docs.djangoproject.com/es/6.1/releases/5.1.13/) - [el](https://docs.djangoproject.com/el/6.1/releases/5.1.13/) * * [dev](https://docs.djangoproject.com/en/dev/releases/5.1.13/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/5.1.13/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/5.1.13/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/5.1.13/) - [**](#top) # Django 5.1.13 release notes[¶](#django-5-1-13-release-notes "Link to this heading") *October 1, 2025* Django 5.1.13 fixes one security issue with severity “high” and one security issue with severity “low” in 5.1.12. * [Kamer.nl donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 5.1.13 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.11.9/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.11.9/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.11.9/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.11.9/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.11.9/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.11.9/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.11.9/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.11.9/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.11.9/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.11.9/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.11.9/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.11.9/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.11.9/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.11.9/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.11.9/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.11.9/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.11.9/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.11.9/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.11.9/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.11.9/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.11.9/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.11.9/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.11.9/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.11.9/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.11.9/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.11.9/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.11.9/) - [**](#top) # Django 1.11.9 release notes[¶](#django-1-11-9-release-notes "Link to this heading") *January 1, 2018* Django 1.11.9 fixes several bugs in 1.11.8. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a regression in Django 1.11 that added newlines between `MultiWidget`’s subwidgets ([#28890](https://code.djangoproject.com/ticket/28890)). * Fixed incorrect class-based model index name generation for models with quoted `db_table` ([#28876](https://code.djangoproject.com/ticket/28876)). * Fixed incorrect foreign key constraint name for models with quoted `db_table` ([#28876](https://code.djangoproject.com/ticket/28876)). * Fixed a regression in caching of a `GenericForeignKey` when the referenced model instance uses more than one level of multi-table inheritance ([#28856](https://code.djangoproject.com/ticket/28856)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Alexander Blank donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.11.9 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/3.1.4/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/3.1.4/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/3.1.4/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/3.1.4/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/3.1.4/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/3.1.4/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/3.1.4/) - [it](https://docs.djangoproject.com/it/6.1/releases/3.1.4/) - [id](https://docs.djangoproject.com/id/6.1/releases/3.1.4/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/3.1.4/) - [es](https://docs.djangoproject.com/es/6.1/releases/3.1.4/) - [el](https://docs.djangoproject.com/el/6.1/releases/3.1.4/) * * [dev](https://docs.djangoproject.com/en/dev/releases/3.1.4/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/3.1.4/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/3.1.4/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/3.1.4/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/3.1.4/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/3.1.4/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/3.1.4/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/3.1.4/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/3.1.4/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/3.1.4/) - [**](#top) # Django 3.1.4 release notes[¶](#django-3-1-4-release-notes "Link to this heading") *December 1, 2020* Django 3.1.4 fixes several bugs in 3.1.3. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed setting the `Content-Length` HTTP header in `AsyncRequestFactory` ([#32162](https://code.djangoproject.com/ticket/32162)). * Fixed passing extra HTTP headers to `AsyncRequestFactory` request methods ([#32159](https://code.djangoproject.com/ticket/32159)). * Fixed crash of key transforms for [`JSONField`](../../ref/models/fields/#django.db.models.JSONField "django.db.models.JSONField") on PostgreSQL when using on a `Subquery()` annotation ([#32182](https://code.djangoproject.com/ticket/32182)). * Fixed a regression in Django 3.1 that caused a crash of auto-reloader for certain invocations of `runserver` on Windows with Python 3.7 and below ([#32202](https://code.djangoproject.com/ticket/32202)). * Fixed a regression in Django 3.1 that caused the incorrect grouping by a `Q` object annotation ([#32200](https://code.djangoproject.com/ticket/32200)). * Fixed a regression in Django 3.1 that caused suppressing connection errors when [`JSONField`](../../ref/models/fields/#django.db.models.JSONField "django.db.models.JSONField") is used on SQLite ([#32224](https://code.djangoproject.com/ticket/32224)). * Fixed a crash on SQLite, when `QuerySet.values()/values_list()` contained key transforms for [`JSONField`](../../ref/models/fields/#django.db.models.JSONField "django.db.models.JSONField") returning non-string primitive values ([#32203](https://code.djangoproject.com/ticket/32203)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Lukasz Baczynski donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 3.1.4 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/topics/db/tablespaces/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/db/tablespaces/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/db/tablespaces/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/db/tablespaces/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/db/tablespaces/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/db/tablespaces/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/db/tablespaces/) - [it](https://docs.djangoproject.com/it/6.1/topics/db/tablespaces/) - [id](https://docs.djangoproject.com/id/6.1/topics/db/tablespaces/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/db/tablespaces/) - [es](https://docs.djangoproject.com/es/6.1/topics/db/tablespaces/) - [el](https://docs.djangoproject.com/el/6.1/topics/db/tablespaces/) * * [dev](https://docs.djangoproject.com/en/dev/topics/db/tablespaces/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/db/tablespaces/) * [5.2](https://docs.djangoproject.com/en/5.2/topics/db/tablespaces/) * [5.1](https://docs.djangoproject.com/en/5.1/topics/db/tablespaces/) * [5.0](https://docs.djangoproject.com/en/5.0/topics/db/tablespaces/) * [4.2](https://docs.djangoproject.com/en/4.2/topics/db/tablespaces/) * [4.1](https://docs.djangoproject.com/en/4.1/topics/db/tablespaces/) * [4.0](https://docs.djangoproject.com/en/4.0/topics/db/tablespaces/) * [3.2](https://docs.djangoproject.com/en/3.2/topics/db/tablespaces/) * [3.1](https://docs.djangoproject.com/en/3.1/topics/db/tablespaces/) * [3.0](https://docs.djangoproject.com/en/3.0/topics/db/tablespaces/) * [2.2](https://docs.djangoproject.com/en/2.2/topics/db/tablespaces/) * [2.1](https://docs.djangoproject.com/en/2.1/topics/db/tablespaces/) * [2.0](https://docs.djangoproject.com/en/2.0/topics/db/tablespaces/) * [1.11](https://docs.djangoproject.com/en/1.11/topics/db/tablespaces/) * [1.10](https://docs.djangoproject.com/en/1.10/topics/db/tablespaces/) * [1.9](https://docs.djangoproject.com/en/1.9/topics/db/tablespaces/) * [1.8](https://docs.djangoproject.com/en/1.8/topics/db/tablespaces/) - [**](#top) # Tablespaces[¶](#tablespaces "Link to this heading") A common paradigm for optimizing performance in database systems is the use of [tablespaces](https://en.wikipedia.org/wiki/Tablespace) to organize disk layout. Warning Django does not create the tablespaces for you. Please refer to your database engine’s documentation for details on creating and managing tablespaces. ## Declaring tablespaces for tables[¶](#declaring-tablespaces-for-tables "Link to this heading") A tablespace can be specified for the table generated by a model by supplying the [`db_tablespace`](../../../ref/models/options/#django.db.models.Options.db_tablespace "django.db.models.Options.db_tablespace") option inside the model’s `class Meta`. This option also affects tables automatically created for [`ManyToManyField`](../../../ref/models/fields/#django.db.models.ManyToManyField "django.db.models.ManyToManyField")s in the model. You can use the [`DEFAULT_TABLESPACE`](../../../ref/settings/#std-setting-DEFAULT_TABLESPACE) setting to specify a default value for [`db_tablespace`](../../../ref/models/options/#django.db.models.Options.db_tablespace "django.db.models.Options.db_tablespace"). This is useful for setting a tablespace for the built-in Django apps and other applications whose code you cannot control. ## Declaring tablespaces for indexes[¶](#declaring-tablespaces-for-indexes "Link to this heading") You can pass the [`db_tablespace`](../../../ref/models/indexes/#django.db.models.Index.db_tablespace "django.db.models.Index.db_tablespace") option to an `Index` constructor to specify the name of a tablespace to use for the index. For single field indexes, you can pass the [`db_tablespace`](../../../ref/models/fields/#django.db.models.Field.db_tablespace "django.db.models.Field.db_tablespace") option to a `Field` constructor to specify an alternate tablespace for the field’s column index. If the column doesn’t have an index, the option is ignored. You can use the [`DEFAULT_INDEX_TABLESPACE`](../../../ref/settings/#std-setting-DEFAULT_INDEX_TABLESPACE) setting to specify a default value for [`db_tablespace`](../../../ref/models/fields/#django.db.models.Field.db_tablespace "django.db.models.Field.db_tablespace"). If [`db_tablespace`](../../../ref/models/fields/#django.db.models.Field.db_tablespace "django.db.models.Field.db_tablespace") isn’t specified and you didn’t set [`DEFAULT_INDEX_TABLESPACE`](../../../ref/settings/#std-setting-DEFAULT_INDEX_TABLESPACE), the index is created in the same tablespace as the tables. ## An example[¶](#an-example "Link to this heading") ``` class TablespaceExample(models.Model): name = models.CharField(max_length=30, db_index=True, db_tablespace="indexes") data = models.CharField(max_length=255, db_index=True) shortcut = models.CharField(max_length=7) edges = models.ManyToManyField(to="self", db_tablespace="indexes") class Meta: db_tablespace = "tables" indexes = [models.Index(fields=["shortcut"], db_tablespace="other_indexes")] ``` In this example, the tables generated by the `TablespaceExample` model (i.e. the model table and the many-to-many table) would be stored in the `tables` tablespace. The index for the name field and the indexes on the many-to-many table would be stored in the `indexes` tablespace. The `data` field would also generate an index, but no tablespace for it is specified, so it would be stored in the model tablespace `tables` by default. The index for the `shortcut` field would be stored in the `other_indexes` tablespace. ## Database support[¶](#database-support "Link to this heading") PostgreSQL and Oracle support tablespaces. SQLite, MariaDB and MySQL don’t. When you use a backend that lacks support for tablespaces, Django ignores all tablespace-related options. [**Back to Top](#top) ## Additional Information ### Support Django! * [Francisco Muñoz Cuevas donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Tablespaces](#) * [Declaring tablespaces for tables](#declaring-tablespaces-for-tables) * [Declaring tablespaces for indexes](#declaring-tablespaces-for-indexes) * [An example](#an-example) * [Database support](#database-support) ---- url: https://docs.djangoproject.com/en/6.1/topics/db/examples/many_to_one/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/db/examples/many_to_one/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/db/examples/many_to_one/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/db/examples/many_to_one/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/db/examples/many_to_one/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/db/examples/many_to_one/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/db/examples/many_to_one/) - [it](https://docs.djangoproject.com/it/6.1/topics/db/examples/many_to_one/) - [id](https://docs.djangoproject.com/id/6.1/topics/db/examples/many_to_one/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/db/examples/many_to_one/) - [es](https://docs.djangoproject.com/es/6.1/topics/db/examples/many_to_one/) - [el](https://docs.djangoproject.com/el/6.1/topics/db/examples/many_to_one/) * * [dev](https://docs.djangoproject.com/en/dev/topics/db/examples/many_to_one/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/db/examples/many_to_one/) * [5.2](https://docs.djangoproject.com/en/5.2/topics/db/examples/many_to_one/) * [5.1](https://docs.djangoproject.com/en/5.1/topics/db/examples/many_to_one/) * [5.0](https://docs.djangoproject.com/en/5.0/topics/db/examples/many_to_one/) * [4.2](https://docs.djangoproject.com/en/4.2/topics/db/examples/many_to_one/) * [4.1](https://docs.djangoproject.com/en/4.1/topics/db/examples/many_to_one/) * [4.0](https://docs.djangoproject.com/en/4.0/topics/db/examples/many_to_one/) * [3.2](https://docs.djangoproject.com/en/3.2/topics/db/examples/many_to_one/) * [3.1](https://docs.djangoproject.com/en/3.1/topics/db/examples/many_to_one/) * [3.0](https://docs.djangoproject.com/en/3.0/topics/db/examples/many_to_one/) * [2.2](https://docs.djangoproject.com/en/2.2/topics/db/examples/many_to_one/) * [2.1](https://docs.djangoproject.com/en/2.1/topics/db/examples/many_to_one/) * [2.0](https://docs.djangoproject.com/en/2.0/topics/db/examples/many_to_one/) * [1.11](https://docs.djangoproject.com/en/1.11/topics/db/examples/many_to_one/) * [1.10](https://docs.djangoproject.com/en/1.10/topics/db/examples/many_to_one/) * [1.9](https://docs.djangoproject.com/en/1.9/topics/db/examples/many_to_one/) * [1.8](https://docs.djangoproject.com/en/1.8/topics/db/examples/many_to_one/) - [**](#top) # Many-to-one relationships[¶](#many-to-one-relationships "Link to this heading") To define a many-to-one relationship, use [`ForeignKey`](../../../../ref/models/fields/#django.db.models.ForeignKey "django.db.models.ForeignKey"). In this example, a `Reporter` can be associated with many `Article` objects, but an `Article` can only have one `Reporter` object: ``` from django.db import models class Reporter(models.Model): first_name = models.CharField(max_length=30) last_name = models.CharField(max_length=30) email = models.EmailField() def __str__(self): return f"{self.first_name} {self.last_name}" class Article(models.Model): headline = models.CharField(max_length=100) pub_date = models.DateField() reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE) def __str__(self): return self.headline class Meta: ordering = ["headline"] ``` What follows are examples of operations that can be performed using the Python API facilities. Create a few Reporters: ``` >>> r = Reporter(first_name="John", last_name="Smith", email="john@example.com") >>> r.save() >>> r2 = Reporter(first_name="Paul", last_name="Jones", email="paul@example.com") >>> r2.save() ``` Create an Article: ``` >>> from datetime import date >>> a = Article(id=None, headline="This is a test", pub_date=date(2005, 7, 27), reporter=r) >>> a.save() >>> a.reporter.id 1 >>> a.reporter ``` Note that you must save an object before it can be assigned to a foreign key relationship. For example, creating an `Article` with unsaved `Reporter` raises `ValueError`: ``` >>> r3 = Reporter(first_name="John", last_name="Smith", email="john@example.com") >>> Article.objects.create( ... headline="This is a test", pub_date=date(2005, 7, 27), reporter=r3 ... ) Traceback (most recent call last): ... ValueError: save() prohibited to prevent data loss due to unsaved related object 'reporter'. ``` Article objects have access to their related Reporter objects: ``` >>> r = a.reporter ``` Create an Article via the Reporter object: ``` >>> new_article = r.article_set.create( ... headline="John's second story", pub_date=date(2005, 7, 29) ... ) >>> new_article >>> new_article.reporter >>> new_article.reporter.id 1 ``` Create a new article: ``` >>> new_article2 = Article.objects.create( ... headline="Paul's story", pub_date=date(2006, 1, 17), reporter=r ... ) >>> new_article2.reporter >>> new_article2.reporter.id 1 >>> r.article_set.all() , , ]> ``` Add the same article to a different article set - check that it moves: ``` >>> r2.article_set.add(new_article2) >>> new_article2.reporter.id 2 >>> new_article2.reporter ``` Adding an object of the wrong type raises TypeError: ``` >>> r.article_set.add(r2) Traceback (most recent call last): ... TypeError: 'Article' instance expected, got >>> r.article_set.all() , ]> >>> r2.article_set.all() ]> >>> r.article_set.count() 2 >>> r2.article_set.count() 1 ``` Note that in the last example the article has moved from John to Paul. Related managers support field lookups as well. The API automatically follows relationships as far as you need. Use double underscores to separate relationships. This works as many levels deep as you want. There’s no limit. For example: ``` >>> r.article_set.filter(headline__startswith="This") ]> # Find all Articles for any Reporter whose first name is "John". >>> Article.objects.filter(reporter__first_name="John") , ]> ``` Exact match is implied here: ``` >>> Article.objects.filter(reporter__first_name="John") , ]> ``` Query twice over the related field. This translates to an AND condition in the WHERE clause: ``` >>> Article.objects.filter(reporter__first_name="John", reporter__last_name="Smith") , ]> ``` For the related lookup you can supply a primary key value or pass the related object explicitly: ``` >>> Article.objects.filter(reporter__pk=1) , ]> >>> Article.objects.filter(reporter=1) , ]> >>> Article.objects.filter(reporter=r) , ]> >>> Article.objects.filter(reporter__in=[1, 2]).distinct() , , ]> >>> Article.objects.filter(reporter__in=[r, r2]).distinct() , , ]> ``` You can also use a queryset instead of a literal list of instances: ``` >>> Article.objects.filter( ... reporter__in=Reporter.objects.filter(first_name="John") ... ).distinct() , ]> ``` Querying in the opposite direction: ``` >>> Reporter.objects.filter(article__pk=1) ]> >>> Reporter.objects.filter(article=1) ]> >>> Reporter.objects.filter(article=a) ]> >>> Reporter.objects.filter(article__headline__startswith="This") , , ]> >>> Reporter.objects.filter(article__headline__startswith="This").distinct() ]> ``` Counting in the opposite direction works in conjunction with `distinct()`: ``` >>> Reporter.objects.filter(article__headline__startswith="This").count() 3 >>> Reporter.objects.filter(article__headline__startswith="This").distinct().count() 1 ``` Queries can go round in circles: ``` >>> Reporter.objects.filter(article__reporter__first_name__startswith="John") , , , ]> >>> Reporter.objects.filter(article__reporter__first_name__startswith="John").distinct() ]> >>> Reporter.objects.filter(article__reporter=r).distinct() ]> ``` If you delete a reporter, their articles will be deleted (assuming that the ForeignKey was defined with [`django.db.models.ForeignKey.on_delete`](../../../../ref/models/fields/#django.db.models.ForeignKey.on_delete "django.db.models.ForeignKey.on_delete") set to `CASCADE`, which is the default): ``` >>> Article.objects.all() , , ]> >>> Reporter.objects.order_by("first_name") , ]> >>> r2.delete() >>> Article.objects.all() , ]> >>> Reporter.objects.order_by("first_name") ]> ``` You can delete using a JOIN in the query: ``` >>> Reporter.objects.filter(article__headline__startswith="This").delete() >>> Reporter.objects.all() >>> Article.objects.all() ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [Florian Demmer donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Many-to-one relationships](#) ---- url: https://docs.djangoproject.com/en/6.1/ref/template-response/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/template-response/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/template-response/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/template-response/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/template-response/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/template-response/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/template-response/) - [it](https://docs.djangoproject.com/it/6.1/ref/template-response/) - [id](https://docs.djangoproject.com/id/6.1/ref/template-response/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/template-response/) - [es](https://docs.djangoproject.com/es/6.1/ref/template-response/) - [el](https://docs.djangoproject.com/el/6.1/ref/template-response/) * * [dev](https://docs.djangoproject.com/en/dev/ref/template-response/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/template-response/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/template-response/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/template-response/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/template-response/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/template-response/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/template-response/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/template-response/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/template-response/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/template-response/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/template-response/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/template-response/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/template-response/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/template-response/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/template-response/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/template-response/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/template-response/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/template-response/) - [**](#top) # `TemplateResponse` and `SimpleTemplateResponse`[¶](#module-django.template.response "Link to this heading") Standard [`HttpResponse`](../request-response/#django.http.HttpResponse "django.http.HttpResponse") objects are static structures. They are provided with a block of pre-rendered content at time of construction, and while that content can be modified, it isn’t in a form that makes it easy to perform modifications. However, it can sometimes be beneficial to allow decorators or middleware to modify a response *after* it has been constructed by the view. For example, you may want to change the template that is used, or put additional data into the context. TemplateResponse provides a way to do just that. Unlike basic [`HttpResponse`](../request-response/#django.http.HttpResponse "django.http.HttpResponse") objects, TemplateResponse objects retain the details of the template and context that was provided by the view to compute the response. The final output of the response is not computed until it is needed, later in the response process. ## `SimpleTemplateResponse` objects[¶](#simpletemplateresponse-objects "Link to this heading") * *class *SimpleTemplateResponse[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L10)[¶](#django.template.response.SimpleTemplateResponse "Link to this definition") ### Attributes[¶](#attributes "Link to this heading") * SimpleTemplateResponse.template\_name[¶](#django.template.response.SimpleTemplateResponse.template_name "Link to this definition") The name of the template to be rendered. Accepts a backend-dependent template object (such as those returned by [`get_template()`](../../topics/templates/#django.template.loader.get_template "django.template.loader.get_template")), the name of a template, or a list of template names. Example: `['foo.html', 'path/to/bar.html']` - SimpleTemplateResponse.context\_data[¶](#django.template.response.SimpleTemplateResponse.context_data "Link to this definition") The context data to be used when rendering the template. It must be a [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)"). Example: `{'foo': 123}` * SimpleTemplateResponse.rendered\_content[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L82)[¶](#django.template.response.SimpleTemplateResponse.rendered_content "Link to this definition") The current rendered value of the response content, using the current template and context data. - SimpleTemplateResponse.is\_rendered[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L122)[¶](#django.template.response.SimpleTemplateResponse.is_rendered "Link to this definition") A boolean indicating whether the response content has been rendered. ### Methods[¶](#methods "Link to this heading") * SimpleTemplateResponse.\_\_init\_\_(*template*, *context=None*, *content\_type=None*, *status=None*, *charset=None*, *using=None*, *headers=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L13)[¶](#django.template.response.SimpleTemplateResponse.__init__ "Link to this definition") Instantiates a [`SimpleTemplateResponse`](#django.template.response.SimpleTemplateResponse "django.template.response.SimpleTemplateResponse") object with the given template, context, content type, HTTP status, and charset. * `template` A backend-dependent template object (such as those returned by [`get_template()`](../../topics/templates/#django.template.loader.get_template "django.template.loader.get_template")), the name of a template, or a list of template names. * `context` A [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") of values to add to the template context. By default, this is an empty dictionary. * `content_type` The value included in the HTTP `Content-Type` header, including the MIME type specification and the character set encoding. If `content_type` is specified, then its value is used. Otherwise, `'text/html'` is used. * `status` The HTTP status code for the response. * `charset` The charset in which the response will be encoded. If not given it will be extracted from `content_type`, and if that is unsuccessful, the [`DEFAULT_CHARSET`](../settings/#std-setting-DEFAULT_CHARSET) setting will be used. * `using` The [`NAME`](../settings/#std-setting-TEMPLATES-NAME) of a template engine to use for loading the template. * `headers` A [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") of HTTP headers to add to the response. - SimpleTemplateResponse.resolve\_context(*context*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L78)[¶](#django.template.response.SimpleTemplateResponse.resolve_context "Link to this definition") Preprocesses context data that will be used for rendering a template. Accepts a [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") of context data. By default, returns the same [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)"). Override this method in order to customize the context. * SimpleTemplateResponse.resolve\_template(*template*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L69)[¶](#django.template.response.SimpleTemplateResponse.resolve_template "Link to this definition") Resolves the template instance to use for rendering. Accepts a backend-dependent template object (such as those returned by [`get_template()`](../../topics/templates/#django.template.loader.get_template "django.template.loader.get_template")), the name of a template, or a list of template names. Returns the backend-dependent template object instance to be rendered. Override this method in order to customize template loading. - SimpleTemplateResponse.add\_post\_render\_callback()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L94)[¶](#django.template.response.SimpleTemplateResponse.add_post_render_callback "Link to this definition") Add a callback that will be invoked after rendering has taken place. This hook can be used to defer certain processing operations (such as caching) until after rendering has occurred. If the [`SimpleTemplateResponse`](#django.template.response.SimpleTemplateResponse "django.template.response.SimpleTemplateResponse") has already been rendered, the callback will be invoked immediately. When called, callbacks will be passed a single argument – the rendered [`SimpleTemplateResponse`](#django.template.response.SimpleTemplateResponse "django.template.response.SimpleTemplateResponse") instance. If the callback returns a value that is not `None`, this will be used as the response instead of the original response object (and will be passed to the next post rendering callback etc.) * SimpleTemplateResponse.render()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L105)[¶](#django.template.response.SimpleTemplateResponse.render "Link to this definition") Sets `response.content` to the result obtained by [`SimpleTemplateResponse.rendered_content`](#django.template.response.SimpleTemplateResponse.rendered_content "django.template.response.SimpleTemplateResponse.rendered_content"), runs all post-rendering callbacks, and returns the resulting response object. `render()` will only have an effect the first time it is called. On subsequent calls, it will return the result obtained from the first call. ## `TemplateResponse` objects[¶](#templateresponse-objects "Link to this heading") * *class *TemplateResponse[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L147)[¶](#django.template.response.TemplateResponse "Link to this definition") `TemplateResponse` is a subclass of [`SimpleTemplateResponse`](#django.template.response.SimpleTemplateResponse "django.template.response.SimpleTemplateResponse") that knows about the current [`HttpRequest`](../request-response/#django.http.HttpRequest "django.http.HttpRequest"). ### Methods[¶](#id1 "Link to this heading") * TemplateResponse.\_\_init\_\_(*request*, *template*, *context=None*, *content\_type=None*, *status=None*, *charset=None*, *using=None*, *headers=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/response.py#L150)[¶](#django.template.response.TemplateResponse.__init__ "Link to this definition") Instantiates a [`TemplateResponse`](#django.template.response.TemplateResponse "django.template.response.TemplateResponse") object with the given request, template, context, content type, HTTP status, and charset. * `request` An [`HttpRequest`](../request-response/#django.http.HttpRequest "django.http.HttpRequest") instance. * `template` A backend-dependent template object (such as those returned by [`get_template()`](../../topics/templates/#django.template.loader.get_template "django.template.loader.get_template")), the name of a template, or a list of template names. * `context` A [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") of values to add to the template context. By default, this is an empty dictionary. * `content_type` The value included in the HTTP `Content-Type` header, including the MIME type specification and the character set encoding. If `content_type` is specified, then its value is used. Otherwise, `'text/html'` is used. * `status` The HTTP status code for the response. * `charset` The charset in which the response will be encoded. If not given it will be extracted from `content_type`, and if that is unsuccessful, the [`DEFAULT_CHARSET`](../settings/#std-setting-DEFAULT_CHARSET) setting will be used. * `using` The [`NAME`](../settings/#std-setting-TEMPLATES-NAME) of a template engine to use for loading the template. * `headers` A [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") of HTTP headers to add to the response. ## The rendering process[¶](#the-rendering-process "Link to this heading") Before a [`TemplateResponse`](#django.template.response.TemplateResponse "django.template.response.TemplateResponse") instance can be returned to the client, it must be rendered. The rendering process takes the intermediate representation of template and context, and turns it into the final byte stream that can be served to the client. There are three circumstances under which a `TemplateResponse` will be rendered: * When the `TemplateResponse` instance is explicitly rendered, using the [`SimpleTemplateResponse.render()`](#django.template.response.SimpleTemplateResponse.render "django.template.response.SimpleTemplateResponse.render") method. * When the content of the response is explicitly set by assigning `response.content`. * After passing through template response middleware, but before passing through response middleware. A `TemplateResponse` can only be rendered once. The first call to [`SimpleTemplateResponse.render()`](#django.template.response.SimpleTemplateResponse.render "django.template.response.SimpleTemplateResponse.render") sets the content of the response; subsequent rendering calls do not change the response content. However, when `response.content` is explicitly assigned, the change is always applied. If you want to force the content to be re-rendered, you can reevaluate the rendered content, and assign the content of the response manually: ``` # Set up a rendered TemplateResponse >>> from django.template.response import TemplateResponse >>> t = TemplateResponse(request, "original.html", {}) >>> t.render() >>> print(t.content) Original content # Re-rendering doesn't change content >>> t.template_name = "new.html" >>> t.render() >>> print(t.content) Original content # Assigning content does change, no render() call required >>> t.content = t.rendered_content >>> print(t.content) New content ``` ### Post-render callbacks[¶](#post-render-callbacks "Link to this heading") Some operations – such as caching – cannot be performed on an unrendered template. They must be performed on a fully complete and rendered response. If you’re using middleware, you can do that. Middleware provides multiple opportunities to process a response on exit from a view. If you put behavior in the response middleware, it’s guaranteed to execute after template rendering has taken place. However, if you’re using a decorator, the same opportunities do not exist. Any behavior defined in a decorator is handled immediately. To compensate for this (and any other analogous use cases), [`TemplateResponse`](#django.template.response.TemplateResponse "django.template.response.TemplateResponse") allows you to register callbacks that will be invoked when rendering has completed. Using this callback, you can defer critical processing until a point where you can guarantee that rendered content will be available. To define a post-render callback, define a function that takes a single argument – response – and register that function with the template response: ``` from django.template.response import TemplateResponse def my_render_callback(response): # Do content-sensitive processing do_post_processing() def my_view(request): # Create a response response = TemplateResponse(request, "mytemplate.html", {}) # Register the callback response.add_post_render_callback(my_render_callback) # Return the response return response ``` `my_render_callback()` will be invoked after the `mytemplate.html` has been rendered, and will be provided the fully rendered [`TemplateResponse`](#django.template.response.TemplateResponse "django.template.response.TemplateResponse") instance as an argument. If the template has already been rendered, the callback will be invoked immediately. ## Using `TemplateResponse` and `SimpleTemplateResponse`[¶](#using-templateresponse-and-simpletemplateresponse "Link to this heading") A [`TemplateResponse`](#django.template.response.TemplateResponse "django.template.response.TemplateResponse") object can be used anywhere that a normal [`django.http.HttpResponse`](../request-response/#django.http.HttpResponse "django.http.HttpResponse") can be used. It can also be used as an alternative to calling [`render()`](../../topics/http/shortcuts/#django.shortcuts.render "django.shortcuts.render"). For example, the following view returns a [`TemplateResponse`](#django.template.response.TemplateResponse "django.template.response.TemplateResponse") with a template and a context containing a queryset: ``` from django.template.response import TemplateResponse def blog_index(request): return TemplateResponse( request, "entry_list.html", {"entries": Entry.objects.all()} ) ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [DoctorC donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [`TemplateResponse` and `SimpleTemplateResponse`](#) * [`SimpleTemplateResponse` objects](#simpletemplateresponse-objects) * [Attributes](#attributes) * [Methods](#methods) * [`TemplateResponse` objects](#templateresponse-objects) * [Methods](#id1) * [The rendering process](#the-rendering-process) * [Post-render callbacks](#post-render-callbacks) * [Using `TemplateResponse` and `SimpleTemplateResponse`](#using-templateresponse-and-simpletemplateresponse) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.6.2/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.6.2/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.6.2/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.6.2/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.6.2/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.6.2/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.6.2/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.6.2/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.6.2/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.6.2/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.6.2/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.6.2/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.6.2/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.6.2/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.6.2/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.6.2/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.6.2/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.6.2/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.6.2/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.6.2/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.6.2/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.6.2/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.6.2/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.6.2/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.6.2/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.6.2/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.6.2/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.6.2/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.6.2/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.6.2/) - [**](#top) # Django 1.6.2 release notes[¶](#django-1-6-2-release-notes "Link to this heading") *February 6, 2014* This is Django 1.6.2, a bugfix release for Django 1.6. Django 1.6.2 fixes several bugs in 1.6.1: * Prevented the base geometry object of a prepared geometry to be garbage collected, which could lead to crash Django ([#21662](https://code.djangoproject.com/ticket/21662)). * Fixed a crash when executing the [`changepassword`](../../ref/django-admin/#django-admin-changepassword) command when the user object representation contained non-ASCII characters ([#21627](https://code.djangoproject.com/ticket/21627)). * The [`collectstatic`](../../ref/contrib/staticfiles/#django-admin-collectstatic) command will raise an error rather than default to using the current working directory if [`STATIC_ROOT`](../../ref/settings/#std-setting-STATIC_ROOT) is not set. Combined with the `--clear` option, the previous behavior could wipe anything below the current working directory ([#21581](https://code.djangoproject.com/ticket/21581)). * Fixed mail encoding on Python 3.3.3+ ([#21093](https://code.djangoproject.com/ticket/21093)). * Fixed an issue where when `settings.DATABASES['default']['AUTOCOMMIT'] = False`, the connection wasn’t in autocommit mode but Django pretended it was. * Fixed a regression in multiple-table inheritance `exclude()` queries ([#21787](https://code.djangoproject.com/ticket/21787)). * Added missing items to `django.utils.timezone.__all__` ([#21880](https://code.djangoproject.com/ticket/21880)). * Fixed a field misalignment issue with `select_related()` and model inheritance ([#21413](https://code.djangoproject.com/ticket/21413)). * Fixed join promotion for negated `AND` conditions ([#21748](https://code.djangoproject.com/ticket/21748)). * Oracle database introspection now works with boolean and float fields ([#19884](https://code.djangoproject.com/ticket/19884)). * Fixed an issue where lazy objects weren’t actually marked as safe when passed through [`mark_safe()`](../../ref/utils/#django.utils.safestring.mark_safe "django.utils.safestring.mark_safe") and could end up being double-escaped ([#21882](https://code.djangoproject.com/ticket/21882)). Additionally, Django’s vendored version of six, `django.utils.six` has been upgraded to the latest release (1.5.2). [**Back to Top](#top) ## Additional Information ### Support Django! * [Michael Aschauer donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.6.2 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/5.2.14/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/5.2.14/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/5.2.14/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/5.2.14/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/5.2.14/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/5.2.14/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/5.2.14/) - [it](https://docs.djangoproject.com/it/6.1/releases/5.2.14/) - [id](https://docs.djangoproject.com/id/6.1/releases/5.2.14/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/5.2.14/) - [es](https://docs.djangoproject.com/es/6.1/releases/5.2.14/) - [el](https://docs.djangoproject.com/el/6.1/releases/5.2.14/) * * [dev](https://docs.djangoproject.com/en/dev/releases/5.2.14/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/5.2.14/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/5.2.14/) - [**](#top) # Django 5.2.14 release notes[¶](#django-5-2-14-release-notes "Link to this heading") *May 5, 2026* Django 5.2.14 fixes three security issues with severity “low” in 5.2.13. [**Back to Top](#top) ## Additional Information ### Support Django! * [Kono Analytics donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 5.2.14 release notes](#) * [CVE-2026-5766: Potential denial-of-service vulnerability in ASGI requests via file upload limit bypass](#cve-2026-5766-potential-denial-of-service-vulnerability-in-asgi-requests-via-file-upload-limit-bypass) * [CVE-2026-35192: Session fixation via public cached pages and `SESSION_SAVE_EVERY_REQUEST`](#cve-2026-35192-session-fixation-via-public-cached-pages-and-session-save-every-request) * [CVE-2026-6907: Potential exposure of private data due to incorrect handling of `Vary: *` in `UpdateCacheMiddleware`](#cve-2026-6907-potential-exposure-of-private-data-due-to-incorrect-handling-of-vary-in-updatecachemiddleware) ---- url: https://docs.djangoproject.com/en/6.1/intro/tutorial01/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/intro/tutorial01/) - [sv](https://docs.djangoproject.com/sv/6.1/intro/tutorial01/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/intro/tutorial01/) - [pl](https://docs.djangoproject.com/pl/6.1/intro/tutorial01/) - [ko](https://docs.djangoproject.com/ko/6.1/intro/tutorial01/) - [ja](https://docs.djangoproject.com/ja/6.1/intro/tutorial01/) - [it](https://docs.djangoproject.com/it/6.1/intro/tutorial01/) - [id](https://docs.djangoproject.com/id/6.1/intro/tutorial01/) - [fr](https://docs.djangoproject.com/fr/6.1/intro/tutorial01/) - [es](https://docs.djangoproject.com/es/6.1/intro/tutorial01/) - [el](https://docs.djangoproject.com/el/6.1/intro/tutorial01/) * * [dev](https://docs.djangoproject.com/en/dev/intro/tutorial01/) * [6.0](https://docs.djangoproject.com/en/6.0/intro/tutorial01/) * [5.2](https://docs.djangoproject.com/en/5.2/intro/tutorial01/) * [5.1](https://docs.djangoproject.com/en/5.1/intro/tutorial01/) * [5.0](https://docs.djangoproject.com/en/5.0/intro/tutorial01/) * [4.2](https://docs.djangoproject.com/en/4.2/intro/tutorial01/) * [4.1](https://docs.djangoproject.com/en/4.1/intro/tutorial01/) * [4.0](https://docs.djangoproject.com/en/4.0/intro/tutorial01/) * [3.2](https://docs.djangoproject.com/en/3.2/intro/tutorial01/) * [3.1](https://docs.djangoproject.com/en/3.1/intro/tutorial01/) * [3.0](https://docs.djangoproject.com/en/3.0/intro/tutorial01/) * [2.2](https://docs.djangoproject.com/en/2.2/intro/tutorial01/) * [2.1](https://docs.djangoproject.com/en/2.1/intro/tutorial01/) * [2.0](https://docs.djangoproject.com/en/2.0/intro/tutorial01/) * [1.11](https://docs.djangoproject.com/en/1.11/intro/tutorial01/) * [1.10](https://docs.djangoproject.com/en/1.10/intro/tutorial01/) * [1.9](https://docs.djangoproject.com/en/1.9/intro/tutorial01/) * [1.8](https://docs.djangoproject.com/en/1.8/intro/tutorial01/) - [**](#top) # Writing your first Django app, part 1[¶](#writing-your-first-django-app-part-1 "Link to this heading") Let’s learn by example. Throughout this tutorial, we’ll walk you through the creation of a basic poll application. It’ll consist of two parts: * A public site that lets people view polls and vote in them. * An admin site that lets you add, change, and delete polls. We’ll assume you have [Django installed](../install/) already. You can tell Django is installed and which version by running the following command in a shell prompt (indicated by the $ prefix): /  ``` $ python -m django --version ``` ** ``` ...\> py -m django --version ``` ** If Django is installed, you should see the version of your installation. If it isn’t, you’ll get an error telling “No module named django”. This tutorial is written for Django 6.1, which supports Python 3.12 and later. If the Django version doesn’t match, you can refer to the tutorial for your version of Django by using the version switcher at the bottom right corner of this page, or update Django to the newest version. If you’re using an older version of Python, check [What Python version can I use with Django?](../../faq/install/#faq-python-version-support) to find a compatible version of Django. Where to get help: If you’re having trouble going through this tutorial, please head over to the [Getting Help](../../faq/help/) section of the FAQ. ## Creating a project[¶](#creating-a-project "Link to this heading") If this is your first time using Django, you’ll have to take care of some initial setup. Namely, you’ll need to auto-generate some code that establishes a Django [project](../../glossary/#term-project) – a collection of settings for an instance of Django, including database configuration, Django-specific options and application-specific settings. From the command line, `cd` into a directory where you’d like to store your code and run the following command to bootstrap a new Django project: /  ``` $ django-admin startproject mysite djangotutorial ``` ** ``` ...\> django-admin startproject mysite djangotutorial ``` ** This will create a directory `djangotutorial` with a project called `mysite` inside. The directory name doesn’t matter to Django; you can rename it to anything you like. If it didn’t work, see [Problems running django-admin](../../faq/troubleshooting/#troubleshooting-django-admin). Note You’ll need to avoid naming projects after built-in Python or Django components. In particular, this means you should avoid using names like `django` (which will conflict with Django itself) or `test` (which conflicts with a built-in Python package). Let’s look at what [`startproject`](../../ref/django-admin/#django-admin-startproject) created: ``` djangotutorial/ manage.py mysite/ __init__.py settings.py urls.py asgi.py wsgi.py ``` These files are: * `manage.py`: A command-line utility that lets you interact with this Django project in various ways. You can read all the details about `manage.py` in [django-admin and manage.py](../../ref/django-admin/). * `mysite/`: A directory that is the actual Python package for your project. Its name is the Python package name you’ll need to use to import anything inside it (e.g. `mysite.urls`). * `mysite/__init__.py`: An empty file that tells Python that this directory should be considered a Python package. If you’re a Python beginner, read [more about packages](https://docs.python.org/3/tutorial/modules.html#tut-packages "(in Python v3.15)") in the official Python docs. * `mysite/settings.py`: Settings/configuration for this Django project. [Django settings](../../topics/settings/) will tell you all about how settings work. * `mysite/urls.py`: The URL declarations for this Django project; a “table of contents” of your Django-powered site. You can read more about URLs in [URL dispatcher](../../topics/http/urls/). * `mysite/asgi.py`: An entry-point for ASGI-compatible web servers to serve your project. See [How to deploy with ASGI](../../howto/deployment/asgi/) for more details. * `mysite/wsgi.py`: An entry-point for WSGI-compatible web servers to serve your project. See [How to deploy with WSGI](../../howto/deployment/wsgi/) for more details. ## The development server[¶](#the-development-server "Link to this heading") Let’s verify your Django project works. Change into the `djangotutorial` directory, if you haven’t already, and run the following commands: /  ``` $ python manage.py runserver ``` ** ``` ...\> py manage.py runserver ``` ** You’ll see the following output on the command line: ``` Performing system checks... System check identified no issues (0 silenced). You have unapplied migrations; your app may not work properly until they are applied. Run 'python manage.py migrate' to apply them. October 20, 2026 - 15:50:53 Django version 6.1, using settings 'mysite.settings' Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C. WARNING: This is a development server. Do not use it in a production setting. Use a production WSGI or ASGI server instead. For more information on production servers see: https://docs.djangoproject.com/en/6.1/howto/deployment/ ``` Note Ignore the warning about unapplied database migrations for now; we’ll deal with the database shortly. Now that the server’s running, visit with your web browser. You’ll see a “Congratulations!” page, with a rocket taking off. It worked! You’ve started the Django development server, a lightweight web server written purely in Python. We’ve included this with Django so you can develop things rapidly, without having to deal with configuring a production server – such as Apache – until you’re ready for production. Now’s a good time to note: **don’t** use this server in anything resembling a production environment. It’s intended only for use while developing. (We’re in the business of making web frameworks, not web servers.) (To serve the site on a different port, see the [`runserver`](../../ref/django-admin/#django-admin-runserver) reference.) Automatic reloading of [`runserver`](../../ref/django-admin/#django-admin-runserver) The development server automatically reloads Python code for each request as needed. You don’t need to restart the server for code changes to take effect. However, some actions like adding files don’t trigger a restart, so you’ll have to restart the server in these cases. ## Creating the Polls app[¶](#creating-the-polls-app "Link to this heading") Now that your environment – a “project” – is set up, you’re set to start doing work. Each application you write in Django consists of a Python package that follows a certain convention. Django comes with a utility that automatically generates the basic directory structure of an app, so you can focus on writing code rather than creating directories. Projects vs. apps What’s the difference between a project and an app? An app is a web application that does something – e.g., a blog system, a database of public records or a small poll app. A project is a collection of configuration and apps for a particular website. A project can contain multiple apps. An app can be in multiple projects. Your apps can live anywhere in your [Python path](https://docs.python.org/3/tutorial/modules.html#tut-searchpath "(in Python v3.15)"). In this tutorial, we’ll create our poll app inside the `djangotutorial` folder. To create your app, make sure you’re in the same directory as `manage.py` and type this command: /  ``` $ python manage.py startapp polls ``` ** ``` ...\> py manage.py startapp polls ``` ** That’ll create a directory `polls`, which is laid out like this: ``` polls/ __init__.py admin.py apps.py migrations/ __init__.py models.py tests.py views.py ``` This directory structure will house the poll application. ## Write your first view[¶](#write-your-first-view "Link to this heading") Let’s write the first view. Open the file `polls/views.py` and put the following Python code in it: `polls/views.py`[¶](#id1 "Link to this code")** ``` from django.http import HttpResponse def index(request): return HttpResponse("Hello, world. You're at the polls index.") ``` This is the most basic view possible in Django. To access it in a browser, we need to map it to a URL - and for this we need to define a URL configuration, or “URLconf” for short. These URL configurations are defined inside each Django app, and they are Python files named `urls.py`. To define a URLconf for the `polls` app, create a file `polls/urls.py` with the following content: `polls/urls.py`[¶](#id2 "Link to this code")** ``` from django.urls import path from . import views urlpatterns = [ path("", views.index, name="index"), ] ``` Your app directory should now look like: ``` polls/ __init__.py admin.py apps.py migrations/ __init__.py models.py tests.py urls.py views.py ``` The next step is to configure the root URLconf in the `mysite` project to include the URLconf defined in `polls.urls`. To do this, add an import for `django.urls.include` in `mysite/urls.py` and insert an [`include()`](../../ref/urls/#django.urls.include "django.urls.include") in the `urlpatterns` list, so you have: `mysite/urls.py`[¶](#id3 "Link to this code")** ``` from django.contrib import admin from django.urls import include, path urlpatterns = [ path("polls/", include("polls.urls")), path("admin/", admin.site.urls), ] ``` The [`path()`](../../ref/urls/#django.urls.path "django.urls.path") function expects at least two arguments: `route` and `view`. The [`include()`](../../ref/urls/#django.urls.include "django.urls.include") function allows referencing other URLconfs. Whenever Django encounters [`include()`](../../ref/urls/#django.urls.include "django.urls.include"), it chops off whatever part of the URL matched up to that point and sends the remaining string to the included URLconf for further processing. The idea behind [`include()`](../../ref/urls/#django.urls.include "django.urls.include") is to make it easy to plug-and-play URLs. Since polls are in their own URLconf (`polls/urls.py`), they can be placed under “/polls/”, or under “/fun\_polls/”, or under “/content/polls/”, or any other path root, and the app will still work. When to use [`include()`](../../ref/urls/#django.urls.include "django.urls.include") You should always use `include()` when you include other URL patterns. The only exception is `admin.site.urls`, which is a pre-built URLconf provided by Django for the default admin site. You have now wired an `index` view into the URLconf. Verify it’s working with the following command: /  ``` $ python manage.py runserver ``` ** ``` ...\> py manage.py runserver ``` ** Go to in your browser, and you should see the text “*Hello, world. You’re at the polls index.*”, which you defined in the `index` view. Page not found? If you get an error page here, check that you’re going to and not . When you’re comfortable with the basic request and response flow, read [part 2 of this tutorial](../tutorial02/) to start working with the database. [**Back to Top](#top) ## Additional Information ### Support Django! * [Abraham Mercado Comuna18 donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Writing your first Django app, part 1](#) * [Creating a project](#creating-a-project) * [The development server](#the-development-server) * [Creating the Polls app](#creating-the-polls-app) * [Write your first view](#write-your-first-view) ---- url: https://docs.djangoproject.com/en/6.1/internals/contributing/writing-documentation/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/internals/contributing/writing-documentation/) - [sv](https://docs.djangoproject.com/sv/6.1/internals/contributing/writing-documentation/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/internals/contributing/writing-documentation/) - [pl](https://docs.djangoproject.com/pl/6.1/internals/contributing/writing-documentation/) - [ko](https://docs.djangoproject.com/ko/6.1/internals/contributing/writing-documentation/) - [ja](https://docs.djangoproject.com/ja/6.1/internals/contributing/writing-documentation/) - [it](https://docs.djangoproject.com/it/6.1/internals/contributing/writing-documentation/) - [id](https://docs.djangoproject.com/id/6.1/internals/contributing/writing-documentation/) - [fr](https://docs.djangoproject.com/fr/6.1/internals/contributing/writing-documentation/) - [es](https://docs.djangoproject.com/es/6.1/internals/contributing/writing-documentation/) - [el](https://docs.djangoproject.com/el/6.1/internals/contributing/writing-documentation/) * * [dev](https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/) * [6.0](https://docs.djangoproject.com/en/6.0/internals/contributing/writing-documentation/) * [5.2](https://docs.djangoproject.com/en/5.2/internals/contributing/writing-documentation/) * [5.1](https://docs.djangoproject.com/en/5.1/internals/contributing/writing-documentation/) * [5.0](https://docs.djangoproject.com/en/5.0/internals/contributing/writing-documentation/) * [4.2](https://docs.djangoproject.com/en/4.2/internals/contributing/writing-documentation/) * [4.1](https://docs.djangoproject.com/en/4.1/internals/contributing/writing-documentation/) * [4.0](https://docs.djangoproject.com/en/4.0/internals/contributing/writing-documentation/) * [3.2](https://docs.djangoproject.com/en/3.2/internals/contributing/writing-documentation/) * [3.1](https://docs.djangoproject.com/en/3.1/internals/contributing/writing-documentation/) * [3.0](https://docs.djangoproject.com/en/3.0/internals/contributing/writing-documentation/) * [2.2](https://docs.djangoproject.com/en/2.2/internals/contributing/writing-documentation/) * [2.1](https://docs.djangoproject.com/en/2.1/internals/contributing/writing-documentation/) * [2.0](https://docs.djangoproject.com/en/2.0/internals/contributing/writing-documentation/) * [1.11](https://docs.djangoproject.com/en/1.11/internals/contributing/writing-documentation/) * [1.10](https://docs.djangoproject.com/en/1.10/internals/contributing/writing-documentation/) * [1.9](https://docs.djangoproject.com/en/1.9/internals/contributing/writing-documentation/) * [1.8](https://docs.djangoproject.com/en/1.8/internals/contributing/writing-documentation/) - [**](#top) # Writing documentation[¶](#writing-documentation "Link to this heading") We place high importance on the consistency and readability of documentation. After all, Django was created in a journalism environment! So we treat our documentation like we treat our code: we aim to improve it as often as possible. Documentation changes generally come in two forms: * General improvements: typo corrections, error fixes and better explanations through clearer writing and more examples. * New features: documentation of features that have been added to the framework since the last release. This section explains how writers can craft their documentation changes in the most useful and least error-prone ways. ## The Django documentation process[¶](#the-django-documentation-process "Link to this heading") Though Django’s documentation is intended to be read as HTML at , we edit it as a collection of plain text files written in the reStructuredText markup language for maximum flexibility. We work from the development version of the repository because it has the latest-and-greatest documentation, just as it has the latest-and-greatest code. We also backport documentation fixes and improvements, at the discretion of the merger, to the last release branch. This is because it’s advantageous to have the docs for the last release be up-to-date and correct (see [Differences between versions](../../../intro/whatsnext/#differences-between-doc-versions)). Django’s documentation uses the [Sphinx](https://www.sphinx-doc.org/) documentation system, which in turn is based on [docutils](https://docutils.sourceforge.io/). The basic idea is that lightly-formatted plain-text documentation is transformed into HTML, PDF, and any other output format. Sphinx includes a `sphinx-build` command for turning reStructuredText into other formats, e.g., HTML and PDF. This command is configurable, but the Django documentation includes a `Makefile` that provides a shorter `make html` command. ## How the documentation is organized[¶](#how-the-documentation-is-organized "Link to this heading") The documentation is organized into several categories: * [Tutorials](../../../intro/) take the reader by the hand through a series of steps to create something. The important thing in a tutorial is to help the reader achieve something useful, preferably as early as possible, in order to give them confidence. Explain the nature of the problem we’re solving, so that the reader understands what we’re trying to achieve. Don’t feel that you need to begin with explanations of how things work - what matters is what the reader does, not what you explain. It can be helpful to refer back to what you’ve done and explain afterward. * [Topic guides](../../../topics/) aim to explain a concept or subject at a fairly high level. Link to reference material rather than repeat it. Use examples and don’t be reluctant to explain things that seem very basic to you - it might be the explanation someone else needs. Providing background context helps a newcomer connect the topic to things that they already know. * [Reference guides](../../../ref/) contain technical references for APIs. They describe the functioning of Django’s internal machinery and instruct in its use. Keep reference material tightly focused on the subject. Assume that the reader already understands the basic concepts involved but needs to know or be reminded of how Django does it. Reference guides aren’t the place for general explanation. If you find yourself explaining basic concepts, you may want to move that material to a topic guide. * [How-to guides](../../../howto/) are recipes that take the reader through steps in key subjects. What matters most in a how-to guide is what a user wants to achieve. A how-to should always be result-oriented rather than focused on internal details of how Django implements whatever is being discussed. These guides are more advanced than tutorials and assume some knowledge about how Django works. Assume that the reader has followed the tutorials and don’t hesitate to refer the reader back to the appropriate tutorial rather than repeat the same material. ## How to start contributing documentation[¶](#how-to-start-contributing-documentation "Link to this heading") ### Clone the Django repository to your local machine[¶](#clone-the-django-repository-to-your-local-machine "Link to this heading") If you’d like to start contributing to our docs, get the development version of Django from the source code repository (see [Installing the development version](../../../topics/install/#installing-development-version)): /  ``` $ git clone https://github.com/django/django.git ``` ** ``` ...\> git clone https://github.com/django/django.git ``` ** If you’re planning to submit these changes, you might find it useful to make a fork of the Django repository and clone this fork instead. ### Set up a virtual environment and install dependencies[¶](#set-up-a-virtual-environment-and-install-dependencies "Link to this heading") Create and activate a virtual environment, then install the dependencies: ``` $ python -m venv .venv $ source .venv/bin/activate $ python -m pip install -r docs/requirements.txt ``` ### Build the documentation locally[¶](#build-the-documentation-locally "Link to this heading") We can build HTML output from the `docs` directory: /  ``` $ cd docs $ make html ``` ** ``` ...\> cd docs ...\> make.bat html ``` ** Your locally-built documentation will be accessible at `_build/html/index.html` and it can be viewed in any web browser, though it will be themed differently than the documentation at [docs.djangoproject.com](https://docs.djangoproject.com/). This is OK! If your changes look good on your local machine, they’ll look good on the website. #### Automating documentation rebuilds[¶](#automating-documentation-rebuilds "Link to this heading") [sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/) can be used to automatically rebuild the documentation and reload the documentation page in the browser whenever a file changes. To enable auto-reloading: 1. Install the package: /  ``` $ python -m pip install sphinx-autobuild ``` ** ``` ...\> py -m pip install sphinx-autobuild ``` ** 2. From the `docs` directory, run one of the following commands: * On Linux and macOS: ``` $ SPHINXBUILD=sphinx-autobuild SPHINXOPTS="--open-browser --delay 0" make html ``` * On Windows (Command Prompt): ``` ...\> set SPHINXBUILD=sphinx-autobuild ...\> set SPHINXOPTS=--open-browser --delay 0 ...\> make html ``` * On Windows (PowerShell): ``` PS> $env:SPHINXBUILD="sphinx-autobuild" PS> $env:SPHINXOPTS="--open-browser --delay 0" PS> make html ``` Alternatively, `sphinx-autobuild` can be invoked directly: /  ``` $ sphinx-autobuild . _build/html --open-browser --delay 0 ``` ** ``` ...\> sphinx-autobuild . _build\html --open-browser --delay 0 ``` ** The auto-reloader can be stopped with `Ctrl+C`. ### Making edits to the documentation[¶](#making-edits-to-the-documentation "Link to this heading") The source files are `.txt` files located in the `docs/` directory. These files are written in the reStructuredText markup language. To learn the markup, see the [reStructuredText reference](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index "(in Sphinx v9.1.1)"). To edit this page, for example, we would edit the file [docs/internals/contributing/writing-documentation.txt](https://github.com/django/django/blob/main/docs/internals/contributing/writing-documentation.txt) and rebuild the HTML with `make html`. ### Documentation quality checks[¶](#documentation-quality-checks "Link to this heading") Several checks help maintain Django’s documentation quality, including [spelling](#documentation-spelling-check), [code block formatting](#documentation-code-block-format-check), and [documentation style](#documentation-lint-check). These checks are run automatically in CI and must pass before documentation changes can be merged. They can also be run locally with a single command: /  ``` $ make check ``` ** ``` ...\> make.bat check ``` ** This command runs all current checks and will include any new checks added in the future. #### Spelling check[¶](#spelling-check "Link to this heading") Before you commit your docs, it’s a good idea to run the spelling checker. You’ll need to install [sphinxcontrib-spelling](https://pypi.org/project/sphinxcontrib-spelling/) first. The spell checker also requires a system-level spell checking backend such as [Aspell](http://aspell.net/). Then from the `docs` directory, run: /  ``` $ make spelling ``` ** ``` ...\> make.bat spelling ``` ** Wrong words (if any) along with the file and line number where they occur will be saved to `_build/spelling/output.txt`. If you encounter false-positives (error output that actually is correct), do one of the following: * Surround inline code or brand/technology names with double grave accents (\`\`) * Find synonyms that the spell checker recognizes. * If, and only if, you are sure the word you are using is correct - add it to `docs/spelling_wordlist` (please keep the list in alphabetical order). #### Code block format check[¶](#code-block-format-check "Link to this heading") All Python code blocks should be formatted using the [blacken-docs](https://pypi.org/project/blacken-docs/) auto-formatter. This is automatically run by the [pre-commit hook](../writing-code/coding-style/#coding-style-pre-commit) if configured. The check can also be run manually: provided that `blacken-docs` is installed, run the following command from the `docs` directory: /  ``` $ make black ``` ** ``` ...\> make.bat black ``` ** The formatter will report any issues by printing them to the terminal and will reformat code blocks where possible. #### Documentation lint check[¶](#documentation-lint-check "Link to this heading") Django’s documentation is checked for reStructuredText style and formal issues using [sphinx-lint](https://pypi.org/project/sphinx-lint/). This helps catch problems like stray tabs, trailing whitespace, excessive line length, and similar formatting problems. Once `sphinx-lint` is installed, the check can be run with the following command from the `docs` directory: /  ``` $ make lint ``` ** ``` ...\> make.bat lint ``` ** The command prints any violations to the terminal in the form `path:line: message`. If problems are encountered: * Read the message and fix the indicated issue (for example, remove trailing whitespace, adjust backticks, or replace tabs with spaces). * For long lines consider wrapping text onto new lines or breaking long inline links into named references. The custom line length check should already skip common false positives such as headings, tables and long links. ### Link check[¶](#link-check "Link to this heading") Links in documentation can become broken or changed such that they are no longer the canonical link. Sphinx provides a builder that can check whether the links in the documentation are working. From the `docs` directory, run: /  ``` $ make linkcheck ``` ** ``` ...\> make.bat linkcheck ``` ** Output is printed to the terminal, but can also be found in `_build/linkcheck/output.txt` and `_build/linkcheck/output.json`. Warning The execution of the command requires an internet connection and takes several minutes to complete, because the command tests all the links that are found in the documentation. Entries that have a status of “working” are fine, those that are “unchecked” or “ignored” have been skipped because they either cannot be checked or have matched ignore rules in the configuration. Entries that have a status of “broken” need to be fixed. Those that have a status of “redirected” may need to be updated to point to the canonical location, e.g. the scheme has changed `http://` → `https://`. In certain cases, we do not want to update a “redirected” link, e.g. a rewrite to always point to the latest or stable version of the documentation, e.g. `/en/stable/` → `/en/3.2/`. ## Writing style[¶](#writing-style "Link to this heading") When using pronouns in reference to a hypothetical person, such as “a user with a session cookie”, gender-neutral pronouns (they/their/them) should be used. Instead of: * he or she… use they. * him or her… use them. * his or her… use their. * his or hers… use theirs. * himself or herself… use themselves. Try to avoid using words that minimize the difficulty involved in a task or operation, such as “easily”, “simply”, “just”, “merely”, “straightforward”, and so on. People’s experience may not match your expectations, and they may become frustrated when they do not find a step as “straightforward” or “simple” as it is implied to be. ## Commonly used terms[¶](#commonly-used-terms "Link to this heading") Here are some style guidelines on commonly used terms throughout the documentation: * **Django** – when referring to the framework, capitalize Django. It is lowercase only in Python code and in the djangoproject.com logo. * **email** – no hyphen. * **HTTP** – the expected pronunciation is “Aitch Tee Tee Pee” and therefore should be preceded by “an” and not “a”. * **MySQL**, **PostgreSQL**, **SQLite** * **SQL** – when referring to SQL, the expected pronunciation should be “Ess Queue Ell” and not “sequel”. Thus in a phrase like “Returns an SQL expression”, “SQL” should be preceded by “an” and not “a”. * **Python** – when referring to the language, capitalize Python. * **realize**, **customize**, **initialize**, etc. – use the American “ize” suffix, not “ise.” * **subclass** – it’s a single word without a hyphen, both as a verb (“subclass that model”) and as a noun (“create a subclass”). * **the web**, **web framework** – it’s not capitalized. * **website** – use one word, without capitalization. ## Django-specific terminology[¶](#django-specific-terminology "Link to this heading") * **model** – it’s not capitalized. * **template** – it’s not capitalized. * **URLconf** – use three capitalized letters, with no space before “conf.” * **view** – it’s not capitalized. ## Guidelines for reStructuredText files[¶](#guidelines-for-restructuredtext-files "Link to this heading") These guidelines regulate the format of our reST (reStructuredText) documentation: * In section titles, capitalize only initial words and proper nouns. * Wrap the documentation at 80 characters wide, unless a code example is significantly less readable when split over two lines, or for another good reason. * The main thing to keep in mind as you write and edit docs is that the more semantic markup you can add the better. So: ``` Add ``django.contrib.auth`` to your ``INSTALLED_APPS``... ``` Isn’t nearly as helpful as: ``` Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`... ``` This is because Sphinx will generate proper links for the latter, which greatly helps readers. You can prefix the target with a `~` (that’s a tilde) to get only the “last bit” of that path. So `` :mod:`~django.contrib.auth` `` will display a link with the title “auth”. * Use [`intersphinx`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#module-sphinx.ext.intersphinx "(in Sphinx v9.1.1)") to reference Python’s and Sphinx’ documentation. * Add `.. code-block:: ` to literal blocks so that they get highlighted. Prefer relying on automatic highlighting using `::` (two colons). This has the benefit that if the code contains some invalid syntax, it won’t be highlighted. Adding `.. code-block:: python`, for example, will force highlighting despite invalid syntax. * To improve readability, use `.. admonition:: Descriptive title` rather than `.. note::`. Use these boxes sparingly. * Use these heading styles: ``` === One === Two === Three ----- Four ~~~~ Five ^^^^ ``` * Use [`:rfc:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-rfc "(in Sphinx v9.1.1)") to reference a Request for Comments (RFC) and try to link to the relevant section if possible. For example, use `` :rfc:`2324#section-2.3.2` `` or `` :rfc:`Custom link text <2324#section-2.3.2>` ``. * Use [`:pep:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-pep "(in Sphinx v9.1.1)") to reference a Python Enhancement Proposal (PEP) and try to link to the relevant section if possible. For example, use `` :pep:`20#easter-egg` `` or `` :pep:`Easter Egg <20#easter-egg>` ``. * Use [`:mimetype:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-mimetype "(in Sphinx v9.1.1)") to refer to a MIME Type unless the value is quoted for a code example. * Use [`:envvar:`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-envvar "(in Sphinx v9.1.1)") to refer to an environment variable. You may also need to define a reference to the documentation for that environment variable using [`.. envvar::`](https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-envvar "(in Sphinx v9.1.1)"). * Use [`:cve:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-cve "(in Sphinx v9.1.1)") to reference a Common Vulnerabilities and Exposures (CVE) identifier. For example, use `` :cve:`2019-14232` ``. * When documenting Python objects (classes, methods, attributes, etc.) using [Sphinx directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) such as `.. class::`, `.. method::`, and `.. attribute::`, all content must be properly indented to ensure correct rendering and to support features like automatic table of contents generation. Follow these rules: * The directive itself remains flush with the left margin (no indentation). * All descriptive text under the directive must be indented by 4 spaces. * Multi-line descriptions must keep the same indentation level. * Nested directives (for example, methods inside a class) require an additional 4 spaces of indentation to maintain hierarchy. * Field lists (such as `:param:`, `:returns:`, etc.) must align with the directive’s content level. Example: ``` .. class:: MyClass A brief description of the class. .. method:: my_method(arg1, arg2) Method description. :param arg1: Description of the first parameter :param arg2: Description of the second parameter .. attribute:: my_attribute Attribute description. ``` ## Django-specific markup[¶](#django-specific-markup "Link to this heading") Besides [Sphinx’s built-in markup](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index "(in Sphinx v9.1.1)"), Django’s docs define some extra description units: * Settings: ``` .. setting:: INSTALLED_APPS ``` To link to a setting, use `` :setting:`INSTALLED_APPS` ``. * Template tags: ``` .. templatetag:: regroup ``` To link, use `` :ttag:`regroup` ``. * Template filters: ``` .. templatefilter:: linebreaksbr ``` To link, use `` :tfilter:`linebreaksbr` ``. * Field lookups (i.e. `Foo.objects.filter(bar__exact=whatever)`): ``` .. fieldlookup:: exact ``` To link, use `` :lookup:`exact` ``. * `django-admin` commands: ``` .. django-admin:: migrate ``` To link, use `` :djadmin:`migrate` ``. * `django-admin` command-line options: ``` .. django-admin-option:: --traceback ``` To link, use `` :option:`command_name --traceback` `` (or omit `command_name` for the options shared by all commands like `--verbosity`). * Links to Trac tickets (typically reserved for patch release notes): ``` :ticket:`12345` ``` Django’s documentation uses a custom `console` directive for documenting command-line examples involving `django-admin`, `manage.py`, `python`, etc. In the HTML documentation, it renders a two-tab UI, with one tab showing a Unix-style command prompt and a second tab showing a Windows prompt. For example, you can replace this fragment: ``` use this command: .. code-block:: console $ python manage.py shell ``` with this one: ``` use this command: .. console:: $ python manage.py shell ``` Notice two things: * You usually will replace occurrences of the `.. code-block:: console` directive. * You don’t need to change the actual content of the code example. You still write it assuming a Unix-y environment (i.e. a `'$'` prompt symbol, `'/'` as filesystem path components separator, etc.) The example above will render a code example block with two tabs. The first one will show: ``` $ python manage.py shell ``` (No changes from what `.. code-block:: console` would have rendered). The second one will show: ``` ...\> py manage.py shell ``` ## Documenting new features[¶](#documenting-new-features "Link to this heading") Our policy for new features is: > All documentation of new features should be written in a way that clearly designates the features that are only available in the Django development version. Assume documentation readers are using the latest release, not the development version. Our preferred way for marking new features is by prefacing the features’ documentation with: “`.. versionadded:: X.Y`”, followed by a mandatory blank line and an optional description (indented). General improvements or other changes to the APIs that should be emphasized should use the “`.. versionchanged:: X.Y`” directive (with the same format as the `versionadded` mentioned above). These `versionadded` and `versionchanged` blocks should be “self-contained.” In other words, since we only keep these annotations around for two releases, it’s nice to be able to remove the annotation and its contents without having to reflow, reindent, or edit the surrounding text. For example, instead of putting the entire description of a new or changed feature in a block, do something like this: ``` .. class:: Author(first_name, last_name, middle_name=None) A person who writes books. ``first_name`` is ... ... ``middle_name`` is ... .. versionchanged:: A.B The ``middle_name`` argument was added. ``` Put the changed annotation notes at the bottom of a section, not the top. Also, avoid referring to a specific version of Django outside a `versionadded` or `versionchanged` block. Even inside a block, it’s often redundant to do so as these annotations render as “New in Django A.B:” and “Changed in Django A.B”, respectively. If a function, attribute, etc. is added, it’s also okay to use a `versionadded` annotation like this: ``` .. attribute:: Author.middle_name .. versionadded:: A.B An author's middle name. ``` We can remove the `.. versionadded:: A.B` annotation without any indentation changes when the time comes. ## Minimizing images[¶](#minimizing-images "Link to this heading") Optimize image compression where possible. For PNG files, use OptiPNG and AdvanceCOMP’s `advpng`: /  ``` $ cd docs $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"` $ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"` ``` ** ``` ...\> cd docs ...\> optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path ".\_build\*" -name "*.png"` ...\> advpng -z4 `find . -type f -not -path ".\_build\*" -name "*.png"` ``` ** This is based on OptiPNG version 0.7.5. Older versions may complain about the `-strip all` option being lossy. ## An example[¶](#an-example "Link to this heading") For a quick example of how it all fits together, consider this hypothetical example: * First, the `ref/settings.txt` document could have an overall layout like this: ``` ======== Settings ======== ... .. _available-settings: Available settings ================== ... .. _deprecated-settings: Deprecated settings =================== ... ``` * Next, the `topics/settings.txt` document could contain something like this: ``` You can access a :ref:`listing of all available settings `. For a list of deprecated settings see :ref:`deprecated-settings`. You can find both in the :doc:`settings reference document `. ``` We use the Sphinx [`doc`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc "(in Sphinx v9.1.1)") cross-reference element when we want to link to another document as a whole and the [`ref`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref "(in Sphinx v9.1.1)") element when we want to link to an arbitrary location in a document. * Next, notice how the settings are annotated: ``` .. setting:: ADMINS ADMINS ====== Default: ``[]`` (Empty list) A list of all the people who get code error notifications... ``` This marks up the following header as the “canonical” target for the setting `ADMINS`. This means any time I talk about `ADMINS`, I can reference it using `` :setting:`ADMINS` ``. That’s basically how everything fits together. ## Translating documentation[¶](#translating-documentation "Link to this heading") See [Localizing the Django documentation](../localizing/#translating-documentation) if you’d like to help translate the documentation into another language. ## `django-admin` man page[¶](#django-admin-man-page "Link to this heading") Sphinx can generate a manual page for the [django-admin](../../../ref/django-admin/) command. This is configured in `docs/conf.py`. Unlike other documentation output, this man page should be included in the Django repository and the releases as `docs/man/django-admin.1`. There isn’t a need to update this file when updating the documentation, as it’s updated once as part of the release process. To generate an updated version of the man page, in the `docs` directory, run: /  ``` $ make man ``` ** ``` ...\> make.bat man ``` ** The new man page will be written in `docs/_build/man/django-admin.1`. [**Back to Top](#top) ## Additional Information ### Support Django! * [PlanPros donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Writing documentation](#) * [The Django documentation process](#the-django-documentation-process) * [How the documentation is organized](#how-the-documentation-is-organized) * [How to start contributing documentation](#how-to-start-contributing-documentation) * [Clone the Django repository to your local machine](#clone-the-django-repository-to-your-local-machine) * [Set up a virtual environment and install dependencies](#set-up-a-virtual-environment-and-install-dependencies) * [Build the documentation locally](#build-the-documentation-locally) * [Automating documentation rebuilds](#automating-documentation-rebuilds) * [Making edits to the documentation](#making-edits-to-the-documentation) * [Documentation quality checks](#documentation-quality-checks) * [Spelling check](#spelling-check) * [Code block format check](#code-block-format-check) * [Documentation lint check](#documentation-lint-check) * [Link check](#link-check) * [Writing style](#writing-style) * [Commonly used terms](#commonly-used-terms) * [Django-specific terminology](#django-specific-terminology) * [Guidelines for reStructuredText files](#guidelines-for-restructuredtext-files) * [Django-specific markup](#django-specific-markup) * [Documenting new features](#documenting-new-features) * [Minimizing images](#minimizing-images) * [An example](#an-example) * [Translating documentation](#translating-documentation) * [`django-admin` man page](#django-admin-man-page) ### Getting help * [FAQ](https://docs.djangoproject.com/en/6.1/faq/) Try the FAQ — it's got answers to many common questions. * [Index](https://docs.djangoproject.com/en/stable/genindex/), [Module Index](https://docs.djangoproject.com/en/stable/py-modindex/), or [Table of Contents](https://docs.djangoproject.com/en/stable/contents/) Handy when looking for specific information. * [Django Discord Server](https://chat.djangoproject.com) Join the Django Discord Community. * [Official Django Forum](https://forum.djangoproject.com/) Join the community on the Django Forum. * [Ticket tracker](https://code.djangoproject.com/) Report bugs with Django or Django documentation in our ticket tracker. ### Download: Offline (Django 6.1): [HTML](https://media.djangoproject.com/docs/django-docs-6.1-en.zip) | [PDF](https://app.readthedocs.org/projects/django/downloads/pdf/6.1.x/) | [ePub](https://app.readthedocs.org/projects/django/downloads/epub/6.1.x/)\ Provided by [Read the Docs](https://about.readthedocs.com/). ### Sponsored Fellow, Diamond and Platinum Members [](https://sentry.io/for/django/ "Sentry") * **Sentry** * [Monitor your Django Code Resolve performance bottlenecks and errors using monitoring, replays, logs and Seer an AI agent for debugging.](https://sentry.io/for/django/ "Sentry") [](https://jb.gg/ybja10 "JetBrains") * **JetBrains** * [JetBrains delivers intelligent software solutions that make developers more productive by simplifying their challenging tasks, automating the routine, and helping them adopt the best development practices. PyCharm is the Python IDE for Professional Developers by JetBrains providing a complete set of tools for productive Python, Web and scientific development.](https://jb.gg/ybja10 "JetBrains") [](https://kraken.tech "Kraken Tech") * **Kraken Tech** * [Kraken is the most-loved operating system for energy. Powered by our Utility-Grade AI™ and deep industry know-how, we help utilities transform their technology and operations so they can lead the energy transition. Delivering better outcomes from generation through distribution to supply, Kraken powers 70+ million accounts worldwide, and is on a mission to make a big, green dent in the universe.](https://kraken.tech "Kraken Tech") [](https://posthog.com "PostHog") * **PostHog** * [PostHog is an all-in-one developer platform for building successful products. We provide product analytics, web analytics, session replay, error tracking, feature flags, experiments, surveys, LLM observability, data warehouse, CDP, workflows, logs, and an AI product assistant to help debug your code, ship features faster, and keep all your usage and customer data in one stack.](https://posthog.com "PostHog") - [Become a sponsor](https://www.djangoproject.com/sponsor/) ---- url: https://docs.djangoproject.com/en/6.1/ref/class-based-views/base/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/class-based-views/base/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/class-based-views/base/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/class-based-views/base/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/class-based-views/base/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/class-based-views/base/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/class-based-views/base/) - [it](https://docs.djangoproject.com/it/6.1/ref/class-based-views/base/) - [id](https://docs.djangoproject.com/id/6.1/ref/class-based-views/base/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/class-based-views/base/) - [es](https://docs.djangoproject.com/es/6.1/ref/class-based-views/base/) - [el](https://docs.djangoproject.com/el/6.1/ref/class-based-views/base/) * * [dev](https://docs.djangoproject.com/en/dev/ref/class-based-views/base/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/class-based-views/base/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/class-based-views/base/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/class-based-views/base/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/class-based-views/base/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/class-based-views/base/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/class-based-views/base/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/class-based-views/base/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/class-based-views/base/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/class-based-views/base/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/class-based-views/base/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/class-based-views/base/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/class-based-views/base/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/class-based-views/base/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/class-based-views/base/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/class-based-views/base/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/class-based-views/base/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/class-based-views/base/) - [**](#top) # Base views[¶](#base-views "Link to this heading") The following three classes provide much of the functionality needed to create Django views. You may think of them as *parent* views, which can be used by themselves or inherited from. They may not provide all the capabilities required for projects, in which case there are Mixins and Generic class-based views. Many of Django’s built-in class-based views inherit from other class-based views or various mixins. Because this inheritance chain is very important, the ancestor classes are documented under the section title of **Ancestors (MRO)**. MRO is an acronym for Method Resolution Order. ## `View`[¶](#view "Link to this heading") * *class *django.views.generic.base.View[¶](#django.views.generic.base.View "Link to this definition") The base view class. All other class-based views inherit from this base class. It isn’t strictly a generic view and thus can also be imported from `django.views`. **Method Flowchart** 1. [`setup()`](#django.views.generic.base.View.setup "django.views.generic.base.View.setup") 2. [`dispatch()`](#django.views.generic.base.View.dispatch "django.views.generic.base.View.dispatch") 3. [`http_method_not_allowed()`](#django.views.generic.base.View.http_method_not_allowed "django.views.generic.base.View.http_method_not_allowed") 4. [`options()`](#django.views.generic.base.View.options "django.views.generic.base.View.options") **Example views.py**: ``` from django.http import HttpResponse from django.views import View class MyView(View): def get(self, request, *args, **kwargs): return HttpResponse("Hello, World!") ``` **Example urls.py**: ``` from django.urls import path from myapp.views import MyView urlpatterns = [ path("mine/", MyView.as_view(), name="my-view"), ] ``` **Attributes** * http\_method\_names[¶](#django.views.generic.base.View.http_method_names "Link to this definition") The list of HTTP method names that this view will accept. Default: ``` ["get", "post", "put", "patch", "delete", "head", "options", "trace"] ``` **Methods** * *classmethod *as\_view(*\*\*initkwargs*)[¶](#django.views.generic.base.View.as_view "Link to this definition") Returns a callable view that takes a request and returns a response: ``` response = MyView.as_view()(request) ``` The returned view has `view_class` and `view_initkwargs` attributes. When the view is called during the request/response cycle, the [`setup()`](#django.views.generic.base.View.setup "django.views.generic.base.View.setup") method assigns the [`HttpRequest`](../../request-response/#django.http.HttpRequest "django.http.HttpRequest") to the view’s `request` attribute, and any positional and/or keyword arguments [captured from the URL pattern](../../../topics/http/urls/#how-django-processes-a-request) to the `args` and `kwargs` attributes, respectively. Then [`dispatch()`](#django.views.generic.base.View.dispatch "django.views.generic.base.View.dispatch") is called. If a `View` subclass defines asynchronous (`async def`) method handlers, `as_view()` will mark the returned callable as a coroutine function. An `ImproperlyConfigured` exception will be raised if both asynchronous (`async def`) and synchronous (`def`) handlers are defined on a single view-class. - setup(*request*, *\*args*, *\*\*kwargs*)[¶](#django.views.generic.base.View.setup "Link to this definition") Performs key view initialization prior to [`dispatch()`](#django.views.generic.base.View.dispatch "django.views.generic.base.View.dispatch"). Assigns the [`HttpRequest`](../../request-response/#django.http.HttpRequest "django.http.HttpRequest") to the view’s `request` attribute, and any positional and/or keyword arguments [captured from the URL pattern](../../../topics/http/urls/#how-django-processes-a-request) to the `args` and `kwargs` attributes, respectively. If overriding this method, you must call `super()`. * dispatch(*request*, *\*args*, *\*\*kwargs*)[¶](#django.views.generic.base.View.dispatch "Link to this definition") The `view` part of the view – the method that accepts a `request` argument plus arguments, and returns an HTTP response. The default implementation will inspect the HTTP method and attempt to delegate to a method that matches the HTTP method; a `GET` will be delegated to `get()`, a `POST` to `post()`, and so on. By default, a `HEAD` request will be delegated to `get()`. If you need to handle `HEAD` requests in a different way than `GET`, you can override the `head()` method. See [Supporting other HTTP methods](../../../topics/class-based-views/#supporting-other-http-methods) for an example. - http\_method\_not\_allowed(*request*, *\*args*, *\*\*kwargs*)[¶](#django.views.generic.base.View.http_method_not_allowed "Link to this definition") If the view was called with an HTTP method it doesn’t support, this method is called instead. The default implementation returns `HttpResponseNotAllowed` with the list of allowed methods in the `Allow` header, as required by [**RFC 7231**](https://datatracker.ietf.org/doc/html/rfc7231.html#section-6.5.5). The response body is empty. * options(*request*, *\*args*, *\*\*kwargs*)[¶](#django.views.generic.base.View.options "Link to this definition") Handles responding to requests for the OPTIONS HTTP verb. Returns a response with the `Allow` header containing a list of the view’s allowed HTTP method names. If the other HTTP methods handlers on the class are asynchronous (`async def`) then the response will be wrapped in a coroutine function for use with `await`. ## `TemplateView`[¶](#templateview "Link to this heading") * *class *django.views.generic.base.TemplateView[¶](#django.views.generic.base.TemplateView "Link to this definition") Renders a given template, with the context containing parameters captured in the URL. **Ancestors (MRO)** This view inherits methods and attributes from the following views: * [`django.views.generic.base.TemplateResponseMixin`](../mixins-simple/#django.views.generic.base.TemplateResponseMixin "django.views.generic.base.TemplateResponseMixin") * [`django.views.generic.base.ContextMixin`](../mixins-simple/#django.views.generic.base.ContextMixin "django.views.generic.base.ContextMixin") * [`django.views.generic.base.View`](#django.views.generic.base.View "django.views.generic.base.View") **Method Flowchart** 1. [`setup()`](#django.views.generic.base.View.setup "django.views.generic.base.View.setup") 2. [`dispatch()`](#django.views.generic.base.View.dispatch "django.views.generic.base.View.dispatch") 3. [`http_method_not_allowed()`](#django.views.generic.base.View.http_method_not_allowed "django.views.generic.base.View.http_method_not_allowed") 4. [`get_context_data()`](../mixins-simple/#django.views.generic.base.ContextMixin.get_context_data "django.views.generic.base.ContextMixin.get_context_data") **Example views.py**: ``` from django.views.generic.base import TemplateView from articles.models import Article class HomePageView(TemplateView): template_name = "home.html" def get_context_data(self, **kwargs): context = super().get_context_data(**kwargs) context["latest_articles"] = Article.objects.all()[:5] return context ``` **Example urls.py**: ``` from django.urls import path from myapp.views import HomePageView urlpatterns = [ path("", HomePageView.as_view(), name="home"), ] ``` **Context** * Populated (through [`ContextMixin`](../mixins-simple/#django.views.generic.base.ContextMixin "django.views.generic.base.ContextMixin")) with the keyword arguments captured from the URL pattern that served the view. * You can also add context using the [`extra_context`](../mixins-simple/#django.views.generic.base.ContextMixin.extra_context "django.views.generic.base.ContextMixin.extra_context") keyword argument for [`as_view()`](#django.views.generic.base.View.as_view "django.views.generic.base.View.as_view"). ## `RedirectView`[¶](#redirectview "Link to this heading") * *class *django.views.generic.base.RedirectView[¶](#django.views.generic.base.RedirectView "Link to this definition") Redirects to a given URL. The given URL may contain dictionary-style string formatting, which will be interpolated against the parameters captured in the URL. Because keyword interpolation is *always* done (even if no arguments are passed in), any `"%"` characters in the URL must be written as `"%%"` so that Python will convert them to a single percent sign on output. If the given URL is `None`, Django will return an `HttpResponseGone` (410). **Ancestors (MRO)** This view inherits methods and attributes from the following view: * [`django.views.generic.base.View`](#django.views.generic.base.View "django.views.generic.base.View") **Method Flowchart** 1. [`setup()`](#django.views.generic.base.View.setup "django.views.generic.base.View.setup") 2. [`dispatch()`](#django.views.generic.base.View.dispatch "django.views.generic.base.View.dispatch") 3. [`http_method_not_allowed()`](#django.views.generic.base.View.http_method_not_allowed "django.views.generic.base.View.http_method_not_allowed") 4. [`get_redirect_url()`](#django.views.generic.base.RedirectView.get_redirect_url "django.views.generic.base.RedirectView.get_redirect_url") **Example views.py**: ``` from django.shortcuts import get_object_or_404 from django.views.generic.base import RedirectView from articles.models import Article class ArticleCounterRedirectView(RedirectView): permanent = False query_string = True pattern_name = "article-detail" def get_redirect_url(self, *args, **kwargs): article = get_object_or_404(Article, pk=kwargs["pk"]) article.update_counter() return super().get_redirect_url(*args, **kwargs) ``` **Example urls.py**: ``` from django.urls import path from django.views.generic.base import RedirectView from article.views import ArticleCounterRedirectView, ArticleDetailView urlpatterns = [ path( "counter//", ArticleCounterRedirectView.as_view(), name="article-counter", ), path("details//", ArticleDetailView.as_view(), name="article-detail"), path( "go-to-django/", RedirectView.as_view(url="https://www.djangoproject.com/"), name="go-to-django", ), ] ``` **Attributes** * url[¶](#django.views.generic.base.RedirectView.url "Link to this definition") The URL to redirect to, as a string. Or `None` to raise a 410 (Gone) HTTP error. - pattern\_name[¶](#django.views.generic.base.RedirectView.pattern_name "Link to this definition") The name of the URL pattern to redirect to. Reversing will be done using the same args and kwargs as are passed in for this view. * permanent[¶](#django.views.generic.base.RedirectView.permanent "Link to this definition") Whether the redirect should be permanent. The only difference here is the HTTP status code returned. If `True`, then the redirect will use status code 301. If `False`, then the redirect will use status code 302. By default, `permanent` is `False`. - query\_string[¶](#django.views.generic.base.RedirectView.query_string "Link to this definition") Whether to pass along the GET query string to the new location. If `True`, then the query string is appended to the URL. If `False`, then the query string is discarded. By default, `query_string` is `False`. * preserve\_request[¶](#django.views.generic.base.RedirectView.preserve_request "Link to this definition") New in Django 6.1. Whether to preserve the HTTP method and body during the redirect. If `True`, then the redirect will use status code 307 instead of 302, or 308 instead of 301 when [`permanent`](#django.views.generic.base.RedirectView.permanent "django.views.generic.base.RedirectView.permanent") is `True`. By default, `preserve_request` is `False`. **Methods** * get\_redirect\_url(*\*args*, *\*\*kwargs*)[¶](#django.views.generic.base.RedirectView.get_redirect_url "Link to this definition") Constructs the target URL for redirection. The `args` and `kwargs` arguments are positional and/or keyword arguments [captured from the URL pattern](../../../topics/http/urls/#how-django-processes-a-request), respectively. The default implementation uses [`url`](#django.views.generic.base.RedirectView.url "django.views.generic.base.RedirectView.url") as a starting string and performs expansion of `%` named parameters in that string using the named groups captured in the URL. If [`url`](#django.views.generic.base.RedirectView.url "django.views.generic.base.RedirectView.url") is not set, `get_redirect_url()` tries to reverse the [`pattern_name`](#django.views.generic.base.RedirectView.pattern_name "django.views.generic.base.RedirectView.pattern_name") using what was captured in the URL (both named and unnamed groups are used). If requested by [`query_string`](#django.views.generic.base.RedirectView.query_string "django.views.generic.base.RedirectView.query_string"), it will also append the query string to the generated URL. Subclasses may implement any behavior they wish, as long as the method returns a redirect-ready URL string. [**Back to Top](#top) ## Additional Information ### Support Django! * [Kono Analytics donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Base views](#) * [`View`](#view) * [`TemplateView`](#templateview) * [`RedirectView`](#redirectview) ---- url: https://docs.djangoproject.com/en/6.1/ref/contrib/gis/gdal/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/gis/gdal/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/contrib/gis/gdal/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/contrib/gis/gdal/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/contrib/gis/gdal/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/contrib/gis/gdal/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/contrib/gis/gdal/) - [it](https://docs.djangoproject.com/it/6.1/ref/contrib/gis/gdal/) - [id](https://docs.djangoproject.com/id/6.1/ref/contrib/gis/gdal/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/contrib/gis/gdal/) - [es](https://docs.djangoproject.com/es/6.1/ref/contrib/gis/gdal/) - [el](https://docs.djangoproject.com/el/6.1/ref/contrib/gis/gdal/) * * [dev](https://docs.djangoproject.com/en/dev/ref/contrib/gis/gdal/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/contrib/gis/gdal/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/contrib/gis/gdal/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/contrib/gis/gdal/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/contrib/gis/gdal/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/contrib/gis/gdal/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/contrib/gis/gdal/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/contrib/gis/gdal/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/contrib/gis/gdal/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/contrib/gis/gdal/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/contrib/gis/gdal/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/contrib/gis/gdal/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/contrib/gis/gdal/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/contrib/gis/gdal/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/contrib/gis/gdal/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/contrib/gis/gdal/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/contrib/gis/gdal/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/contrib/gis/gdal/) - [**](#top) # GDAL API[¶](#module-django.contrib.gis.gdal "Link to this heading") ## Overview[¶](#overview "Link to this heading") [GDAL](https://gdal.org/) stands for **Geospatial Data Abstraction Library**, and is a veritable “Swiss army knife” of GIS data functionality. A subset of GDAL is the [OGR](https://gdal.org/user/vector_data_model.html) Simple Features Library, which specializes in reading and writing vector geographic data in a variety of standard formats. GeoDjango provides a high-level Python interface for some of the capabilities of OGR, including the reading and coordinate transformation of vector spatial data and minimal support for GDAL’s features with respect to raster (image) data. Note Although the module is named `gdal`, GeoDjango only supports some of the capabilities of OGR and GDAL’s raster features at this time. ### Sample Data[¶](#sample-data "Link to this heading") The GDAL/OGR tools described here are designed to help you read in your geospatial data, in order for most of them to be useful you have to have some data to work with. If you’re starting out and don’t yet have any data of your own to use, GeoDjango tests contain a number of data sets that you can use for testing. You can download them here: ``` $ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf} $ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/rasters/raster.tif ``` ## Vector Data Source Objects[¶](#vector-data-source-objects "Link to this heading") ### `DataSource`[¶](#datasource "Link to this heading") [`DataSource`](#django.contrib.gis.gdal.DataSource "django.contrib.gis.gdal.DataSource") is a wrapper for the OGR data source object that supports reading data from a variety of OGR-supported geospatial file formats and data sources using a consistent interface. Each data source is represented by a [`DataSource`](#django.contrib.gis.gdal.DataSource "django.contrib.gis.gdal.DataSource") object which contains one or more layers of data. Each layer, represented by a [`Layer`](#django.contrib.gis.gdal.Layer "django.contrib.gis.gdal.Layer") object, contains some number of geographic features ([`Feature`](#django.contrib.gis.gdal.Feature "django.contrib.gis.gdal.Feature")), information about the type of features contained in that layer (e.g. points, polygons, etc.), as well as the names and types of any additional fields ([`Field`](#django.contrib.gis.gdal.Field "django.contrib.gis.gdal.Field")) of data that may be associated with each feature in that layer. * *class *DataSource(*ds\_input*, *encoding='utf-8'*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/datasource.py#L50)[¶](#django.contrib.gis.gdal.DataSource "Link to this definition") The constructor for `DataSource` only requires one parameter: the path of the file you want to read. However, OGR also supports a variety of more complex data sources, including databases, that may be accessed by passing a special name string instead of a path. For more information, see the [OGR Vector Formats](https://gdal.org/drivers/vector/) documentation. The [`name`](#django.contrib.gis.gdal.DataSource.name "django.contrib.gis.gdal.DataSource.name") property of a `DataSource` instance gives the OGR name of the underlying data source that it is using. The optional `encoding` parameter allows you to specify a non-standard encoding of the strings in the source. This is typically useful when you obtain `DjangoUnicodeDecodeError` exceptions while reading field values. Once you’ve created your `DataSource`, you can find out how many layers of data it contains by accessing the [`layer_count`](#django.contrib.gis.gdal.DataSource.layer_count "django.contrib.gis.gdal.DataSource.layer_count") property, or (equivalently) by using the `len()` function. For information on accessing the layers of data themselves, see the next section: ``` >>> from django.contrib.gis.gdal import DataSource >>> ds = DataSource("/path/to/your/cities.shp") >>> ds.name '/path/to/your/cities.shp' >>> ds.layer_count # This file only contains one layer 1 ``` * layer\_count[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/datasource.py#L120)[¶](#django.contrib.gis.gdal.DataSource.layer_count "Link to this definition") Returns the number of layers in the data source. * name[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/datasource.py#L125)[¶](#django.contrib.gis.gdal.DataSource.name "Link to this definition") Returns the name of the data source. ### `Layer`[¶](#layer "Link to this heading") * *class *Layer[¶](#django.contrib.gis.gdal.Layer "Link to this definition") `Layer` is a wrapper for a layer of data in a `DataSource` object. You never create a `Layer` object directly. Instead, you retrieve them from a [`DataSource`](#django.contrib.gis.gdal.DataSource "django.contrib.gis.gdal.DataSource") object, which is essentially a standard Python container of `Layer` objects. For example, you can access a specific layer by its index (e.g. `ds[0]` to access the first layer), or you can iterate over all the layers in the container in a `for` loop. The `Layer` itself acts as a container for geometric features. Typically, all the features in a given layer have the same geometry type. The [`geom_type`](#django.contrib.gis.gdal.Layer.geom_type "django.contrib.gis.gdal.Layer.geom_type") property of a layer is an [`OGRGeomType`](#django.contrib.gis.gdal.OGRGeomType "django.contrib.gis.gdal.OGRGeomType") that identifies the feature type. We can use it to print out some basic information about each layer in a [`DataSource`](#django.contrib.gis.gdal.DataSource "django.contrib.gis.gdal.DataSource"): ``` >>> for layer in ds: ... print('Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name)) ... Layer "cities": 3 Points ``` The example output is from the cities data source, loaded above, which evidently contains one layer, called `"cities"`, which contains three point features. For simplicity, the examples below assume that you’ve stored that layer in the variable `layer`: ``` >>> layer = ds[0] ``` * name[¶](#django.contrib.gis.gdal.Layer.name "Link to this definition") Returns the name of this layer in the data source. ``` >>> layer.name 'cities' ``` * num\_feat[¶](#django.contrib.gis.gdal.Layer.num_feat "Link to this definition") Returns the number of features in the layer. Same as `len(layer)`: ``` >>> layer.num_feat 3 ``` * geom\_type[¶](#django.contrib.gis.gdal.Layer.geom_type "Link to this definition") Returns the geometry type of the layer, as an [`OGRGeomType`](#django.contrib.gis.gdal.OGRGeomType "django.contrib.gis.gdal.OGRGeomType") object: ``` >>> layer.geom_type.name 'Point' ``` * num\_fields[¶](#django.contrib.gis.gdal.Layer.num_fields "Link to this definition") Returns the number of fields in the layer, i.e the number of fields of data associated with each feature in the layer: ``` >>> layer.num_fields 4 ``` * fields[¶](#django.contrib.gis.gdal.Layer.fields "Link to this definition") Returns a list of the names of each of the fields in this layer: ``` >>> layer.fields ['Name', 'Population', 'Density', 'Created'] ``` Returns a list of the data types of each of the fields in this layer. These are subclasses of `Field`, discussed below: ``` >>> [ft.__name__ for ft in layer.field_types] ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate'] ``` * field\_widths[¶](#django.contrib.gis.gdal.Layer.field_widths "Link to this definition") Returns a list of the maximum field widths for each of the fields in this layer: ``` >>> layer.field_widths [80, 11, 24, 10] ``` * field\_precisions[¶](#django.contrib.gis.gdal.Layer.field_precisions "Link to this definition") Returns a list of the numeric precisions for each of the fields in this layer. This is meaningless (and set to zero) for non-numeric fields: ``` >>> layer.field_precisions [0, 0, 15, 0] ``` * extent[¶](#django.contrib.gis.gdal.Layer.extent "Link to this definition") Returns the spatial extent of this layer, as an [`Envelope`](#django.contrib.gis.gdal.Envelope "django.contrib.gis.gdal.Envelope") object: ``` >>> layer.extent.tuple (-104.609252, 29.763374, -95.23506, 38.971823) ``` * srs[¶](#django.contrib.gis.gdal.Layer.srs "Link to this definition") Property that returns the [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") associated with this layer: ``` >>> print(layer.srs) GEOGCS["GCS_WGS_1984", DATUM["WGS_1984", SPHEROID["WGS_1984",6378137,298.257223563]], PRIMEM["Greenwich",0], UNIT["Degree",0.017453292519943295]] ``` If the [`Layer`](#django.contrib.gis.gdal.Layer "django.contrib.gis.gdal.Layer") has no spatial reference information associated with it, `None` is returned. * spatial\_filter[¶](#django.contrib.gis.gdal.Layer.spatial_filter "Link to this definition") Property that may be used to retrieve or set a spatial filter for this layer. A spatial filter can only be set with an [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") instance, a 4-tuple extent, or `None`. When set with something other than `None`, only features that intersect the filter will be returned when iterating over the layer: ``` >>> print(layer.spatial_filter) None >>> print(len(layer)) 3 >>> [feat.get("Name") for feat in layer] ['Pueblo', 'Lawrence', 'Houston'] >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas >>> layer.spatial_filter = ks_extent >>> len(layer) 1 >>> [feat.get("Name") for feat in layer] ['Lawrence'] >>> layer.spatial_filter = None >>> len(layer) 3 ``` * get\_fields()[¶](#django.contrib.gis.gdal.Layer.get_fields "Link to this definition") A method that returns a list of the values of a given field for each feature in the layer: ``` >>> layer.get_fields("Name") ['Pueblo', 'Lawrence', 'Houston'] ``` * get\_geoms(*geos=False*)[¶](#django.contrib.gis.gdal.Layer.get_geoms "Link to this definition") A method that returns a list containing the geometry of each feature in the layer. If the optional argument `geos` is set to `True` then the geometries are converted to [`GEOSGeometry`](../geos/#django.contrib.gis.geos.GEOSGeometry "django.contrib.gis.geos.GEOSGeometry") objects. Otherwise, they are returned as [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") objects: ``` >>> [pt.tuple for pt in layer.get_geoms()] [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)] ``` * test\_capability(*capability*)[¶](#django.contrib.gis.gdal.Layer.test_capability "Link to this definition") Returns a boolean indicating whether this layer supports the given capability (a string). Examples of valid capability strings include: `'RandomRead'`, `'SequentialWrite'`, `'RandomWrite'`, `'FastSpatialFilter'`, `'FastFeatureCount'`, `'FastGetExtent'`, `'CreateField'`, `'Transactions'`, `'DeleteFeature'`, and `'FastSetNextByIndex'`. ### `Feature`[¶](#feature "Link to this heading") * *class *Feature[¶](#django.contrib.gis.gdal.Feature "Link to this definition") `Feature` wraps an OGR feature. You never create a `Feature` object directly. Instead, you retrieve them from a [`Layer`](#django.contrib.gis.gdal.Layer "django.contrib.gis.gdal.Layer") object. Each feature consists of a geometry and a set of fields containing additional properties. The geometry of a field is accessible via its `geom` property, which returns an [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") object. A `Feature` behaves like a standard Python container for its fields, which it returns as [`Field`](#django.contrib.gis.gdal.Field "django.contrib.gis.gdal.Field") objects: you can access a field directly by its index or name, or you can iterate over a feature’s fields, e.g. in a `for` loop. * geom[¶](#django.contrib.gis.gdal.Feature.geom "Link to this definition") Returns the geometry for this feature, as an `OGRGeometry` object: ``` >>> city.geom.tuple (-104.609252, 38.255001) ``` * get[¶](#django.contrib.gis.gdal.Feature.get "Link to this definition") A method that returns the value of the given field (specified by name) for this feature, **not** a `Field` wrapper object: ``` >>> city.get("Population") 102121 ``` * geom\_type[¶](#django.contrib.gis.gdal.Feature.geom_type "Link to this definition") Returns the type of geometry for this feature, as an [`OGRGeomType`](#django.contrib.gis.gdal.OGRGeomType "django.contrib.gis.gdal.OGRGeomType") object. This will be the same for all features in a given layer and is equivalent to the [`Layer.geom_type`](#django.contrib.gis.gdal.Layer.geom_type "django.contrib.gis.gdal.Layer.geom_type") property of the [`Layer`](#django.contrib.gis.gdal.Layer "django.contrib.gis.gdal.Layer") object the feature came from. * num\_fields[¶](#django.contrib.gis.gdal.Feature.num_fields "Link to this definition") Returns the number of fields of data associated with the feature. This will be the same for all features in a given layer and is equivalent to the [`Layer.num_fields`](#django.contrib.gis.gdal.Layer.num_fields "django.contrib.gis.gdal.Layer.num_fields") property of the [`Layer`](#django.contrib.gis.gdal.Layer "django.contrib.gis.gdal.Layer") object the feature came from. * fields[¶](#django.contrib.gis.gdal.Feature.fields "Link to this definition") Returns a list of the names of the fields of data associated with the feature. This will be the same for all features in a given layer and is equivalent to the [`Layer.fields`](#django.contrib.gis.gdal.Layer.fields "django.contrib.gis.gdal.Layer.fields") property of the [`Layer`](#django.contrib.gis.gdal.Layer "django.contrib.gis.gdal.Layer") object the feature came from. * fid[¶](#django.contrib.gis.gdal.Feature.fid "Link to this definition") Returns the feature identifier within the layer: ``` >>> city.fid 0 ``` * layer\_name[¶](#django.contrib.gis.gdal.Feature.layer_name "Link to this definition") Returns the name of the [`Layer`](#django.contrib.gis.gdal.Layer "django.contrib.gis.gdal.Layer") that the feature came from. This will be the same for all features in a given layer: ``` >>> city.layer_name 'cities' ``` * index[¶](#django.contrib.gis.gdal.Feature.index "Link to this definition") A method that returns the index of the given field name. This will be the same for all features in a given layer: ``` >>> city.index("Population") 1 ``` ### `Field`[¶](#field "Link to this heading") * *class *Field[¶](#django.contrib.gis.gdal.Field "Link to this definition") * name[¶](#django.contrib.gis.gdal.Field.name "Link to this definition") Returns the name of this field: ``` >>> city["Name"].name 'Name' ``` * type[¶](#django.contrib.gis.gdal.Field.type "Link to this definition") Returns the OGR type of this field, as an integer. The `FIELD_CLASSES` dictionary maps these values onto subclasses of `Field`: ``` >>> city["Density"].type 2 ``` * type\_name[¶](#django.contrib.gis.gdal.Field.type_name "Link to this definition") Returns a string with the name of the data type of this field: ``` >>> city["Name"].type_name 'String' ``` * value[¶](#django.contrib.gis.gdal.Field.value "Link to this definition") Returns the value of this field. The `Field` class itself returns the value as a string, but each subclass returns the value in the most appropriate form: ``` >>> city["Population"].value 102121 ``` * width[¶](#django.contrib.gis.gdal.Field.width "Link to this definition") Returns the width of this field: ``` >>> city["Name"].width 80 ``` * precision[¶](#django.contrib.gis.gdal.Field.precision "Link to this definition") Returns the numeric precision of this field. This is meaningless (and set to zero) for non-numeric fields: ``` >>> city["Density"].precision 15 ``` * as\_double()[¶](#django.contrib.gis.gdal.Field.as_double "Link to this definition") Returns the value of the field as a double (float): ``` >>> city["Density"].as_double() 874.7 ``` * as\_int()[¶](#django.contrib.gis.gdal.Field.as_int "Link to this definition") Returns the value of the field as an integer: ``` >>> city["Population"].as_int() 102121 ``` * as\_string()[¶](#django.contrib.gis.gdal.Field.as_string "Link to this definition") Returns the value of the field as a string: ``` >>> city["Name"].as_string() 'Pueblo' ``` * as\_datetime()[¶](#django.contrib.gis.gdal.Field.as_datetime "Link to this definition") Returns the value of the field as a tuple of date and time components: ``` >>> city["Created"].as_datetime() (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0)) ``` ### `Driver`[¶](#driver "Link to this heading") * *class *Driver(*dr\_input*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/driver.py#L10)[¶](#django.contrib.gis.gdal.Driver "Link to this definition") The `Driver` class is used internally to wrap an OGR [`DataSource`](#django.contrib.gis.gdal.DataSource "django.contrib.gis.gdal.DataSource") driver. * driver\_count[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/driver.py#L90)[¶](#django.contrib.gis.gdal.Driver.driver_count "Link to this definition") Returns the number of OGR vector drivers currently registered. ## OGR Geometries[¶](#ogr-geometries "Link to this heading") ### `OGRGeometry`[¶](#ogrgeometry "Link to this heading") [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") objects share similar functionality with [`GEOSGeometry`](../geos/#django.contrib.gis.geos.GEOSGeometry "django.contrib.gis.geos.GEOSGeometry") objects and are thin wrappers around OGR’s internal geometry representation. Thus, they allow for more efficient access to data when using [`DataSource`](#django.contrib.gis.gdal.DataSource "django.contrib.gis.gdal.DataSource"). Unlike its GEOS counterpart, [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") supports spatial reference systems and coordinate transformation: ``` >>> from django.contrib.gis.gdal import OGRGeometry >>> polygon = OGRGeometry("POLYGON((0 0, 5 0, 5 5, 0 5))") ``` * *class *OGRGeometry(*geom\_input*, *srs=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L65)[¶](#django.contrib.gis.gdal.OGRGeometry "Link to this definition") This object is a wrapper for the [OGR Geometry](https://gdal.org/api/ogrgeometry_cpp.html#ogrgeometry-class) class. These objects are instantiated directly from the given `geom_input` parameter, which may be a string containing WKT, HEX, GeoJSON, a `buffer` containing WKB data, or an [`OGRGeomType`](#django.contrib.gis.gdal.OGRGeomType "django.contrib.gis.gdal.OGRGeomType") object. These objects are also returned from the [`Feature.geom`](#django.contrib.gis.gdal.Feature.geom "django.contrib.gis.gdal.Feature.geom") attribute, when reading vector data from [`Layer`](#django.contrib.gis.gdal.Layer "django.contrib.gis.gdal.Layer") (which is in turn a part of a [`DataSource`](#django.contrib.gis.gdal.DataSource "django.contrib.gis.gdal.DataSource")). * *classmethod *from\_gml(*gml\_string*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L177)[¶](#django.contrib.gis.gdal.OGRGeometry.from_gml "Link to this definition") Constructs an [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") from the given GML string. * *classmethod *from\_bbox(*bbox*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L164)[¶](#django.contrib.gis.gdal.OGRGeometry.from_bbox "Link to this definition") Constructs a [`Polygon`](#django.contrib.gis.gdal.Polygon "django.contrib.gis.gdal.Polygon") from the given bounding-box (a 4-tuple). * \_\_len\_\_()[¶](#django.contrib.gis.gdal.OGRGeometry.__len__ "Link to this definition") Returns the number of points in a [`LineString`](#django.contrib.gis.gdal.LineString "django.contrib.gis.gdal.LineString"), the number of rings in a [`Polygon`](#django.contrib.gis.gdal.Polygon "django.contrib.gis.gdal.Polygon"), or the number of geometries in a [`GeometryCollection`](#django.contrib.gis.gdal.GeometryCollection "django.contrib.gis.gdal.GeometryCollection"). Not applicable to other geometry types. * \_\_iter\_\_()[¶](#django.contrib.gis.gdal.OGRGeometry.__iter__ "Link to this definition") Iterates over the points in a [`LineString`](#django.contrib.gis.gdal.LineString "django.contrib.gis.gdal.LineString"), the rings in a [`Polygon`](#django.contrib.gis.gdal.Polygon "django.contrib.gis.gdal.Polygon"), or the geometries in a [`GeometryCollection`](#django.contrib.gis.gdal.GeometryCollection "django.contrib.gis.gdal.GeometryCollection"). Not applicable to other geometry types. * \_\_getitem\_\_()[¶](#django.contrib.gis.gdal.OGRGeometry.__getitem__ "Link to this definition") Returns the point at the specified index for a [`LineString`](#django.contrib.gis.gdal.LineString "django.contrib.gis.gdal.LineString"), the interior ring at the specified index for a [`Polygon`](#django.contrib.gis.gdal.Polygon "django.contrib.gis.gdal.Polygon"), or the geometry at the specified index in a [`GeometryCollection`](#django.contrib.gis.gdal.GeometryCollection "django.contrib.gis.gdal.GeometryCollection"). Not applicable to other geometry types. * dimension[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L211)[¶](#django.contrib.gis.gdal.OGRGeometry.dimension "Link to this definition") Returns the number of coordinated dimensions of the geometry, i.e. 0 for points, 1 for lines, and so forth: ``` >>> polygon.dimension 2 ``` * is\_3d[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L274)[¶](#django.contrib.gis.gdal.OGRGeometry.is_3d "Link to this definition") A boolean indicating if this geometry has Z coordinates. * set\_3d(*value*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L278)[¶](#django.contrib.gis.gdal.OGRGeometry.set_3d "Link to this definition") A method that adds or removes the Z coordinate dimension. ``` >>> p = OGRGeometry("POINT (1 2 3)") >>> p.is_3d True >>> p.set_3d(False) >>> p.wkt "POINT (1 2)" ``` * is\_measured[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L288)[¶](#django.contrib.gis.gdal.OGRGeometry.is_measured "Link to this definition") A boolean indicating if this geometry has M coordinates. * set\_measured(*value*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L292)[¶](#django.contrib.gis.gdal.OGRGeometry.set_measured "Link to this definition") A method to add or remove the M coordinate dimension. ``` >>> p = OGRGeometry("POINT (1 2)") >>> p.is_measured False >>> p.set_measured(True) >>> p.wkt "POINT M (1 2 0)" ``` * geom\_count[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L221)[¶](#django.contrib.gis.gdal.OGRGeometry.geom_count "Link to this definition") Returns the number of elements in this geometry: ``` >>> polygon.geom_count 1 ``` * has\_curve[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L304)[¶](#django.contrib.gis.gdal.OGRGeometry.has_curve "Link to this definition") A boolean indicating if this geometry is or contains a curve geometry. * get\_linear\_geometry()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L308)[¶](#django.contrib.gis.gdal.OGRGeometry.get_linear_geometry "Link to this definition") Returns a linear version of the geometry. If no conversion can be made, the original geometry is returned. * get\_curve\_geometry()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L312)[¶](#django.contrib.gis.gdal.OGRGeometry.get_curve_geometry "Link to this definition") Returns a curved version of the geometry. If no conversion can be made, the original geometry is returned. * point\_count[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L226)[¶](#django.contrib.gis.gdal.OGRGeometry.point_count "Link to this definition") Returns the number of points used to describe this geometry: ``` >>> polygon.point_count 4 ``` * num\_points[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L231)[¶](#django.contrib.gis.gdal.OGRGeometry.num_points "Link to this definition") Alias for [`point_count`](#django.contrib.gis.gdal.OGRGeometry.point_count "django.contrib.gis.gdal.OGRGeometry.point_count"). * num\_coords[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L236)[¶](#django.contrib.gis.gdal.OGRGeometry.num_coords "Link to this definition") Alias for [`point_count`](#django.contrib.gis.gdal.OGRGeometry.point_count "django.contrib.gis.gdal.OGRGeometry.point_count"). * geom\_type[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L241)[¶](#django.contrib.gis.gdal.OGRGeometry.geom_type "Link to this definition") Returns the type of this geometry, as an [`OGRGeomType`](#django.contrib.gis.gdal.OGRGeomType "django.contrib.gis.gdal.OGRGeomType") object. * geom\_name[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L246)[¶](#django.contrib.gis.gdal.OGRGeometry.geom_name "Link to this definition") Returns the name of the type of this geometry: ``` >>> polygon.geom_name 'POLYGON' ``` * area[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L251)[¶](#django.contrib.gis.gdal.OGRGeometry.area "Link to this definition") Returns the area of this geometry, or 0 for geometries that do not contain an area: ``` >>> polygon.area 25.0 ``` * envelope[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L259)[¶](#django.contrib.gis.gdal.OGRGeometry.envelope "Link to this definition") Returns the envelope of this geometry, as an [`Envelope`](#django.contrib.gis.gdal.Envelope "django.contrib.gis.gdal.Envelope") object. * extent[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L269)[¶](#django.contrib.gis.gdal.OGRGeometry.extent "Link to this definition") Returns the envelope of this geometry as a 4-tuple, instead of as an [`Envelope`](#django.contrib.gis.gdal.Envelope "django.contrib.gis.gdal.Envelope") object: ``` >>> point.extent (0.0, 0.0, 5.0, 5.0) ``` * srs[¶](#django.contrib.gis.gdal.OGRGeometry.srs "Link to this definition") This property controls the spatial reference for this geometry, or `None` if no spatial reference system has been assigned to it. If assigned, accessing this property returns a [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") object. It may be set with another [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") object, or any input that [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") accepts. Example: ``` >>> city.geom.srs.name 'GCS_WGS_1984' ``` * srid[¶](#django.contrib.gis.gdal.OGRGeometry.srid "Link to this definition") Returns or sets the spatial reference identifier corresponding to [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") of this geometry. Returns `None` if there is no spatial reference information associated with this geometry, or if an SRID cannot be determined. * geos[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L370)[¶](#django.contrib.gis.gdal.OGRGeometry.geos "Link to this definition") Returns a [`GEOSGeometry`](../geos/#django.contrib.gis.geos.GEOSGeometry "django.contrib.gis.geos.GEOSGeometry") object corresponding to this geometry. * gml[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L382)[¶](#django.contrib.gis.gdal.OGRGeometry.gml "Link to this definition") Returns a string representation of this geometry in GML format: ``` >>> OGRGeometry("POINT(1 2)").gml '1,2' ``` * hex[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L387)[¶](#django.contrib.gis.gdal.OGRGeometry.hex "Link to this definition") Returns a string representation of this geometry in HEX WKB format: ``` >>> OGRGeometry("POINT(1 2)").hex '0101000000000000000000F03F0000000000000040' ``` * json[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L392)[¶](#django.contrib.gis.gdal.OGRGeometry.json "Link to this definition") Returns a string representation of this geometry in JSON format: ``` >>> OGRGeometry("POINT(1 2)").json '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }' ``` * kml[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L401)[¶](#django.contrib.gis.gdal.OGRGeometry.kml "Link to this definition") Returns a string representation of this geometry in KML format. * wkb\_size[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L406)[¶](#django.contrib.gis.gdal.OGRGeometry.wkb_size "Link to this definition") Returns the size of the WKB buffer needed to hold a WKB representation of this geometry: ``` >>> OGRGeometry("POINT(1 2)").wkb_size 21 ``` * wkb[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L411)[¶](#django.contrib.gis.gdal.OGRGeometry.wkb "Link to this definition") Returns a `buffer` containing a WKB representation of this geometry. * wkt[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L430)[¶](#django.contrib.gis.gdal.OGRGeometry.wkt "Link to this definition") Returns a string representation of this geometry in WKT format. * ewkt[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L439)[¶](#django.contrib.gis.gdal.OGRGeometry.ewkt "Link to this definition") Returns the EWKT representation of this geometry. * clone()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L448)[¶](#django.contrib.gis.gdal.OGRGeometry.clone "Link to this definition") Returns a new [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") clone of this geometry object. * close\_rings()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L452)[¶](#django.contrib.gis.gdal.OGRGeometry.close_rings "Link to this definition") If there are any rings within this geometry that have not been closed, this routine will do so by adding the starting point to the end: ``` >>> triangle = OGRGeometry("LINEARRING (0 0,0 1,1 0)") >>> triangle.close_rings() >>> triangle.wkt 'LINEARRING (0 0,0 1,1 0,0 0)' ``` * transform(*coord\_trans*, *clone=False*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L461)[¶](#django.contrib.gis.gdal.OGRGeometry.transform "Link to this definition") Transforms this geometry to a different spatial reference system. May take a [`CoordTransform`](#django.contrib.gis.gdal.CoordTransform "django.contrib.gis.gdal.CoordTransform") object, a [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") object, or any other input accepted by [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") (including spatial reference WKT and PROJ strings, or an integer SRID). By default nothing is returned and the geometry is transformed in-place. However, if the `clone` keyword is set to `True` then a transformed clone of this geometry is returned instead. * intersects(*other*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L502)[¶](#django.contrib.gis.gdal.OGRGeometry.intersects "Link to this definition") Returns `True` if this geometry intersects the other, otherwise returns `False`. * equals(*other*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L506)[¶](#django.contrib.gis.gdal.OGRGeometry.equals "Link to this definition") Returns `True` if this geometry is equivalent to the other, otherwise returns `False`. * disjoint(*other*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L510)[¶](#django.contrib.gis.gdal.OGRGeometry.disjoint "Link to this definition") Returns `True` if this geometry is spatially disjoint to (i.e. does not intersect) the other, otherwise returns `False`. * touches(*other*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L514)[¶](#django.contrib.gis.gdal.OGRGeometry.touches "Link to this definition") Returns `True` if this geometry touches the other, otherwise returns `False`. * crosses(*other*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L518)[¶](#django.contrib.gis.gdal.OGRGeometry.crosses "Link to this definition") Returns `True` if this geometry crosses the other, otherwise returns `False`. * within(*other*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L522)[¶](#django.contrib.gis.gdal.OGRGeometry.within "Link to this definition") Returns `True` if this geometry is contained within the other, otherwise returns `False`. * contains(*other*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L526)[¶](#django.contrib.gis.gdal.OGRGeometry.contains "Link to this definition") Returns `True` if this geometry contains the other, otherwise returns `False`. * overlaps(*other*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L530)[¶](#django.contrib.gis.gdal.OGRGeometry.overlaps "Link to this definition") Returns `True` if this geometry overlaps the other, otherwise returns `False`. * boundary()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L543)[¶](#django.contrib.gis.gdal.OGRGeometry.boundary "Link to this definition") The boundary of this geometry, as a new [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") object. * convex\_hull[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L548)[¶](#django.contrib.gis.gdal.OGRGeometry.convex_hull "Link to this definition") The smallest convex polygon that contains this geometry, as a new [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") object. * difference()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L555)[¶](#django.contrib.gis.gdal.OGRGeometry.difference "Link to this definition") Returns the region consisting of the difference of this geometry and the other, as a new [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") object. * intersection()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L562)[¶](#django.contrib.gis.gdal.OGRGeometry.intersection "Link to this definition") Returns the region consisting of the intersection of this geometry and the other, as a new [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") object. * sym\_difference()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L569)[¶](#django.contrib.gis.gdal.OGRGeometry.sym_difference "Link to this definition") Returns the region consisting of the symmetric difference of this geometry and the other, as a new [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") object. * union()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L576)[¶](#django.contrib.gis.gdal.OGRGeometry.union "Link to this definition") Returns the region consisting of the union of this geometry and the other, as a new [`OGRGeometry`](#django.contrib.gis.gdal.OGRGeometry "django.contrib.gis.gdal.OGRGeometry") object. * centroid[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geometries.py#L584)[¶](#django.contrib.gis.gdal.OGRGeometry.centroid "Link to this definition") Returns a [`Point`](#django.contrib.gis.gdal.Point "django.contrib.gis.gdal.Point") representing the centroid of this geometry. * tuple[¶](#django.contrib.gis.gdal.OGRGeometry.tuple "Link to this definition") Returns the coordinates of a point geometry as a tuple, the coordinates of a line geometry as a tuple of tuples, and so forth: ``` >>> OGRGeometry("POINT (1 2)").tuple (1.0, 2.0) >>> OGRGeometry("LINESTRING (1 2,3 4)").tuple ((1.0, 2.0), (3.0, 4.0)) ``` * coords[¶](#django.contrib.gis.gdal.OGRGeometry.coords "Link to this definition") An alias for [`tuple`](#django.contrib.gis.gdal.OGRGeometry.tuple "django.contrib.gis.gdal.OGRGeometry.tuple"). - *class *Point[¶](#django.contrib.gis.gdal.Point "Link to this definition") * x[¶](#django.contrib.gis.gdal.Point.x "Link to this definition") Returns the X coordinate of this point: ``` >>> OGRGeometry("POINT (1 2)").x 1.0 ``` * y[¶](#django.contrib.gis.gdal.Point.y "Link to this definition") Returns the Y coordinate of this point: ``` >>> OGRGeometry("POINT (1 2)").y 2.0 ``` * z[¶](#django.contrib.gis.gdal.Point.z "Link to this definition") Returns the Z coordinate of this point, or `None` if the point does not have a Z coordinate: ``` >>> OGRGeometry("POINT (1 2 3)").z 3.0 ``` * m[¶](#django.contrib.gis.gdal.Point.m "Link to this definition") Returns the M coordinate of this point, or `None` if the Point does not have an M coordinate: ``` >>> OGRGeometry("POINT ZM (1 2 3 4)").m 4.0 ``` * *class *LineString[¶](#django.contrib.gis.gdal.LineString "Link to this definition") * x[¶](#django.contrib.gis.gdal.LineString.x "Link to this definition") Returns a list of X coordinates in this line: ``` >>> OGRGeometry("LINESTRING (1 2,3 4)").x [1.0, 3.0] ``` * y[¶](#django.contrib.gis.gdal.LineString.y "Link to this definition") Returns a list of Y coordinates in this line: ``` >>> OGRGeometry("LINESTRING (1 2,3 4)").y [2.0, 4.0] ``` * z[¶](#django.contrib.gis.gdal.LineString.z "Link to this definition") Returns a list of Z coordinates in this line, or `None` if the line does not have Z coordinates: ``` >>> OGRGeometry("LINESTRING (1 2 3,4 5 6)").z [3.0, 6.0] ``` * m[¶](#django.contrib.gis.gdal.LineString.m "Link to this definition") Returns a list of M coordinates in this line or `None` if the line does not have M coordinates: ``` >>> OGRGeometry("LINESTRING(0 1 2 10, 1 2 3 11, 2 3 4 12)").m [10.0, 11.0, 12.0] ``` - *class *Polygon[¶](#django.contrib.gis.gdal.Polygon "Link to this definition") * shell[¶](#django.contrib.gis.gdal.Polygon.shell "Link to this definition") Returns the shell or exterior ring of this polygon, as a `LinearRing` geometry. * exterior\_ring[¶](#django.contrib.gis.gdal.Polygon.exterior_ring "Link to this definition") An alias for [`shell`](#django.contrib.gis.gdal.Polygon.shell "django.contrib.gis.gdal.Polygon.shell"). * *class *GeometryCollection[¶](#django.contrib.gis.gdal.GeometryCollection "Link to this definition") * add(*geom*)[¶](#django.contrib.gis.gdal.GeometryCollection.add "Link to this definition") Adds a geometry to this geometry collection. Not applicable to other geometry types. ### `OGRGeomType`[¶](#ogrgeomtype "Link to this heading") * *class *OGRGeomType(*type\_input*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geomtype.py#L4)[¶](#django.contrib.gis.gdal.OGRGeomType "Link to this definition") This class allows for the representation of an OGR geometry type in any of several ways: ``` >>> from django.contrib.gis.gdal import OGRGeomType >>> gt1 = OGRGeomType(3) # Using an integer for the type >>> gt2 = OGRGeomType("Polygon") # Using a string >>> gt3 = OGRGeomType("POLYGON") # It's case-insensitive >>> print(gt1 == 3, gt1 == "Polygon") # Equivalence works w/non-OGRGeomType objects True True ``` * name[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geomtype.py#L124)[¶](#django.contrib.gis.gdal.OGRGeomType.name "Link to this definition") Returns a short-hand string form of the OGR Geometry type: ``` >>> gt1.name 'Polygon' ``` * num[¶](#django.contrib.gis.gdal.OGRGeomType.num "Link to this definition") Returns the number corresponding to the OGR geometry type: ``` >>> gt1.num 3 ``` * django[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/geomtype.py#L129)[¶](#django.contrib.gis.gdal.OGRGeomType.django "Link to this definition") Returns the Django field type (a subclass of GeometryField) to use for storing this OGR type, or `None` if there is no appropriate Django type: ``` >>> gt1.django 'PolygonField' ``` ### `Envelope`[¶](#envelope "Link to this heading") * *class *Envelope(*\*args*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L33)[¶](#django.contrib.gis.gdal.Envelope "Link to this definition") Represents an OGR Envelope structure that contains the minimum and maximum X, Y coordinates for a rectangle bounding box. The naming of the variables is compatible with the OGR Envelope C structure. * min\_x[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L156)[¶](#django.contrib.gis.gdal.Envelope.min_x "Link to this definition") The value of the minimum X coordinate. * min\_y[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L161)[¶](#django.contrib.gis.gdal.Envelope.min_y "Link to this definition") The value of the maximum X coordinate. * max\_x[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L166)[¶](#django.contrib.gis.gdal.Envelope.max_x "Link to this definition") The value of the minimum Y coordinate. * max\_y[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L171)[¶](#django.contrib.gis.gdal.Envelope.max_y "Link to this definition") The value of the maximum Y coordinate. * ur[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L176)[¶](#django.contrib.gis.gdal.Envelope.ur "Link to this definition") The upper-right coordinate, as a tuple. * ll[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L181)[¶](#django.contrib.gis.gdal.Envelope.ll "Link to this definition") The lower-left coordinate, as a tuple. * tuple[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L186)[¶](#django.contrib.gis.gdal.Envelope.tuple "Link to this definition") A tuple representing the envelope. * wkt[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L191)[¶](#django.contrib.gis.gdal.Envelope.wkt "Link to this definition") A string representing this envelope as a polygon in WKT format. * expand\_to\_include(*\*args*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/envelope.py#L107)[¶](#django.contrib.gis.gdal.Envelope.expand_to_include "Link to this definition") ## Coordinate System Objects[¶](#coordinate-system-objects "Link to this heading") ### `SpatialReference`[¶](#spatialreference "Link to this heading") * *class *SpatialReference(*srs\_input*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L45)[¶](#django.contrib.gis.gdal.SpatialReference "Link to this definition") Spatial reference objects are initialized on the given `srs_input`, which may be one of the following: * OGC Well Known Text (WKT) (a string) * EPSG code (integer or string) * PROJ string * A shorthand string for well-known standards (`'WGS84'`, `'WGS72'`, `'NAD27'`, `'NAD83'`) Example: ``` >>> wgs84 = SpatialReference("WGS84") # shorthand string >>> wgs84 = SpatialReference(4326) # EPSG code >>> wgs84 = SpatialReference("EPSG:4326") # EPSG string >>> proj = "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs " >>> wgs84 = SpatialReference(proj) # PROJ string >>> wgs84 = SpatialReference("""GEOGCS["WGS 84", ... DATUM["WGS_1984", ... SPHEROID["WGS 84",6378137,298.257223563, ... AUTHORITY["EPSG","7030"]], ... AUTHORITY["EPSG","6326"]], ... PRIMEM["Greenwich",0, ... AUTHORITY["EPSG","8901"]], ... UNIT["degree",0.01745329251994328, ... AUTHORITY["EPSG","9122"]], ... AUTHORITY["EPSG","4326"]]""") # OGC WKT ``` * \_\_getitem\_\_(*target*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L113)[¶](#django.contrib.gis.gdal.SpatialReference.__getitem__ "Link to this definition") Returns the value of the given string attribute node, `None` if the node doesn’t exist. Can also take a tuple as a parameter, (target, child), where child is the index of the attribute in the WKT. For example: ``` >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]' >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326 >>> print(srs["GEOGCS"]) WGS 84 >>> print(srs["DATUM"]) WGS_1984 >>> print(srs["AUTHORITY"]) EPSG >>> print(srs["AUTHORITY", 1]) # The authority value 4326 >>> print(srs["TOWGS84", 4]) # the fourth value in this wkt 0 >>> print(srs["UNIT|AUTHORITY"]) # For the units authority, have to use the pipe symbol. EPSG >>> print(srs["UNIT|AUTHORITY", 1]) # The authority value for the units 9122 ``` * attr\_value(*target*, *index=0*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L151)[¶](#django.contrib.gis.gdal.SpatialReference.attr_value "Link to this definition") The attribute value for the given target node (e.g. `'PROJCS'`). The index keyword specifies an index of the child node to return. * auth\_name(*target*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L160)[¶](#django.contrib.gis.gdal.SpatialReference.auth_name "Link to this definition") Returns the authority name for the given string target node. * auth\_code(*target*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L166)[¶](#django.contrib.gis.gdal.SpatialReference.auth_code "Link to this definition") Returns the authority code for the given string target node. * clone()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L172)[¶](#django.contrib.gis.gdal.SpatialReference.clone "Link to this definition") Returns a clone of this spatial reference object. * identify\_epsg()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L180)[¶](#django.contrib.gis.gdal.SpatialReference.identify_epsg "Link to this definition") This method inspects the WKT of this `SpatialReference` and will add EPSG authority nodes where an EPSG identifier is applicable. * from\_esri()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L176)[¶](#django.contrib.gis.gdal.SpatialReference.from_esri "Link to this definition") Morphs this SpatialReference from ESRI’s format to EPSG * to\_esri()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L187)[¶](#django.contrib.gis.gdal.SpatialReference.to_esri "Link to this definition") Morphs this SpatialReference to ESRI’s format. * validate()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L191)[¶](#django.contrib.gis.gdal.SpatialReference.validate "Link to this definition") Checks to see if the given spatial reference is valid, if not an exception will be raised. * import\_epsg(*epsg*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L305)[¶](#django.contrib.gis.gdal.SpatialReference.import_epsg "Link to this definition") Import spatial reference from EPSG code. * import\_proj(*proj*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L309)[¶](#django.contrib.gis.gdal.SpatialReference.import_proj "Link to this definition") Import spatial reference from PROJ string. * import\_user\_input(*user\_input*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L313)[¶](#django.contrib.gis.gdal.SpatialReference.import_user_input "Link to this definition") - import\_wkt(*wkt*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L317)[¶](#django.contrib.gis.gdal.SpatialReference.import_wkt "Link to this definition") Import spatial reference from WKT. * import\_xml(*xml*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L321)[¶](#django.contrib.gis.gdal.SpatialReference.import_xml "Link to this definition") Import spatial reference from XML. * name[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L197)[¶](#django.contrib.gis.gdal.SpatialReference.name "Link to this definition") Returns the name of this Spatial Reference. * srid[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L209)[¶](#django.contrib.gis.gdal.SpatialReference.srid "Link to this definition") Returns the SRID of top-level authority, or `None` if undefined. * linear\_name[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L218)[¶](#django.contrib.gis.gdal.SpatialReference.linear_name "Link to this definition") Returns the name of the linear units. * linear\_units[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L224)[¶](#django.contrib.gis.gdal.SpatialReference.linear_units "Link to this definition") Returns the value of the linear units. * angular\_name[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L230)[¶](#django.contrib.gis.gdal.SpatialReference.angular_name "Link to this definition") Returns the name of the angular units.” * angular\_units[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L236)[¶](#django.contrib.gis.gdal.SpatialReference.angular_units "Link to this definition") Returns the value of the angular units. * units[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L242)[¶](#django.contrib.gis.gdal.SpatialReference.units "Link to this definition") Returns a 2-tuple of the units value and the units name and will automatically determines whether to return the linear or angular units. * ellipsoid[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L258)[¶](#django.contrib.gis.gdal.SpatialReference.ellipsoid "Link to this definition") Returns a tuple of the ellipsoid parameters for this spatial reference: (semimajor axis, semiminor axis, and inverse flattening). * semi\_major[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L266)[¶](#django.contrib.gis.gdal.SpatialReference.semi_major "Link to this definition") Returns the semi major axis of the ellipsoid for this spatial reference. * semi\_minor[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L271)[¶](#django.contrib.gis.gdal.SpatialReference.semi_minor "Link to this definition") Returns the semi minor axis of the ellipsoid for this spatial reference. * inverse\_flattening[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L276)[¶](#django.contrib.gis.gdal.SpatialReference.inverse_flattening "Link to this definition") Returns the inverse flattening of the ellipsoid for this spatial reference. * geographic[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L282)[¶](#django.contrib.gis.gdal.SpatialReference.geographic "Link to this definition") Returns `True` if this spatial reference is geographic (root node is `GEOGCS`). * local[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L290)[¶](#django.contrib.gis.gdal.SpatialReference.local "Link to this definition") Returns `True` if this spatial reference is local (root node is `LOCAL_CS`). * projected[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L297)[¶](#django.contrib.gis.gdal.SpatialReference.projected "Link to this definition") Returns `True` if this spatial reference is a projected coordinate system (root node is `PROJCS`). * wkt[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L327)[¶](#django.contrib.gis.gdal.SpatialReference.wkt "Link to this definition") Returns the WKT representation of this spatial reference. * pretty\_wkt[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L332)[¶](#django.contrib.gis.gdal.SpatialReference.pretty_wkt "Link to this definition") Returns the ‘pretty’ representation of the WKT. * proj[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L337)[¶](#django.contrib.gis.gdal.SpatialReference.proj "Link to this definition") Returns the PROJ representation for this spatial reference. * proj4[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L342)[¶](#django.contrib.gis.gdal.SpatialReference.proj4 "Link to this definition") Alias for [`SpatialReference.proj`](#django.contrib.gis.gdal.SpatialReference.proj "django.contrib.gis.gdal.SpatialReference.proj"). * xml[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L347)[¶](#django.contrib.gis.gdal.SpatialReference.xml "Link to this definition") Returns the XML representation of this spatial reference. ### `CoordTransform`[¶](#coordtransform "Link to this heading") * *class *CoordTransform(*source*, *target*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/srs.py#L352)[¶](#django.contrib.gis.gdal.CoordTransform "Link to this definition") Represents a coordinate system transform. It is initialized with two [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference"), representing the source and target coordinate systems, respectively. These objects should be used when performing the same coordinate transformation repeatedly on different geometries: ``` >>> ct = CoordTransform(SpatialReference("WGS84"), SpatialReference("NAD83")) >>> for feat in layer: ... geom = feat.geom # getting clone of feature geometry ... geom.transform(ct) # transforming ... ``` ## Raster Data Objects[¶](#raster-data-objects "Link to this heading") ### `GDALRaster`[¶](#gdalraster "Link to this heading") [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") is a wrapper for the GDAL raster source object that supports reading data from a variety of GDAL-supported geospatial file formats and data sources using a consistent interface. Each data source is represented by a [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") object which contains one or more layers of data named bands. Each band, represented by a [`GDALBand`](#django.contrib.gis.gdal.GDALBand "django.contrib.gis.gdal.GDALBand") object, contains georeferenced image data. For example, an RGB image is represented as three bands: one for red, one for green, and one for blue. Note For raster data there is no difference between a raster instance and its data source. Unlike for the Geometry objects, [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") objects are always a data source. Temporary rasters can be instantiated in memory using the corresponding driver, but they will be of the same class as file-based raster sources. * *class *GDALRaster(*ds\_input*, *write=False*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L78)[¶](#django.contrib.gis.gdal.GDALRaster "Link to this definition") The constructor for `GDALRaster` accepts two parameters. The first parameter defines the raster source, and the second parameter defines if a raster should be opened in write mode. For newly-created rasters, the second parameter is ignored and the new raster is always created in write mode. The first parameter can take three forms: a string or [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") representing a file path (filesystem or GDAL virtual filesystem), a dictionary with values defining a new raster, or a bytes object representing a raster file. If the input is a file path, the raster is opened from there. If the input is raw data in a dictionary, the parameters `width`, `height`, and `srid` are required. If the input is a bytes object, it will be opened using a GDAL virtual filesystem. For a detailed description of how to create rasters using dictionary input, see [Creating rasters from data](#gdal-raster-ds-input). For a detailed description of how to create rasters in the virtual filesystem, see [Using GDAL’s Virtual Filesystem](#gdal-raster-vsimem). The following example shows how rasters can be created from different input sources (using the sample data from the GeoDjango tests; see also the [Sample Data](#gdal-sample-data) section). ``` >>> from django.contrib.gis.gdal import GDALRaster >>> rst = GDALRaster("/path/to/your/raster.tif", write=False) >>> rst.name '/path/to/your/raster.tif' >>> rst.width, rst.height # This file has 163 x 174 pixels (163, 174) >>> rst = GDALRaster( ... { # Creates an in-memory raster ... "srid": 4326, ... "width": 4, ... "height": 4, ... "datatype": 1, ... "bands": [ ... { ... "data": (2, 3), ... "offset": (1, 1), ... "size": (2, 2), ... "shape": (2, 1), ... "nodata_value": 5, ... } ... ], ... } ... ) >>> rst.srs.srid 4326 >>> rst.width, rst.height (4, 4) >>> rst.bands[0].data() array([[5, 5, 5, 5], [5, 2, 3, 5], [5, 2, 3, 5], [5, 5, 5, 5]], dtype=uint8) >>> rst_file = open("/path/to/your/raster.tif", "rb") >>> rst_bytes = rst_file.read() >>> rst = GDALRaster(rst_bytes) >>> rst.is_vsi_based True >>> rst.name # Stored in a random path in the vsimem filesystem. '/vsimem/da300bdb-129d-49a8-b336-e410a9428dad' ``` * name[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L308)[¶](#django.contrib.gis.gdal.GDALRaster.name "Link to this definition") The name of the source which is equivalent to the input file path or the name provided upon instantiation. ``` >>> GDALRaster({"width": 10, "height": 10, "name": "myraster", "srid": 4326}).name 'myraster' ``` - driver[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L316)[¶](#django.contrib.gis.gdal.GDALRaster.driver "Link to this definition") The name of the GDAL driver used to handle the input file. For `GDALRaster`s created from a file, the driver type is detected automatically. The creation of rasters from scratch is an in-memory raster by default (`'MEM'`), but can be altered as needed. For instance, use `GTiff` for a `GeoTiff` file. For a list of file types, see also the [GDAL Raster Formats](https://gdal.org/drivers/raster/) list. An in-memory raster is created through the following example: ``` >>> GDALRaster({"width": 10, "height": 10, "srid": 4326}).driver.name 'MEM' ``` A file based GeoTiff raster is created through the following example: ``` >>> import tempfile >>> rstfile = tempfile.NamedTemporaryFile(suffix=".tif") >>> rst = GDALRaster( ... { ... "driver": "GTiff", ... "name": rstfile.name, ... "srid": 4326, ... "width": 255, ... "height": 255, ... "nr_of_bands": 1, ... } ... ) >>> rst.name '/tmp/tmp7x9H4J.tif' # The exact filename will be different on your computer >>> rst.driver.name 'GTiff' ``` * width[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L324)[¶](#django.contrib.gis.gdal.GDALRaster.width "Link to this definition") The width of the source in pixels (X-axis). ``` >>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).width 10 ``` - height[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L331)[¶](#django.contrib.gis.gdal.GDALRaster.height "Link to this definition") The height of the source in pixels (Y-axis). ``` >>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).height 20 ``` * srs[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L351)[¶](#django.contrib.gis.gdal.GDALRaster.srs "Link to this definition") The spatial reference system of the raster, as a [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") instance. The SRS can be changed by setting it to an other [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") or providing any input that is accepted by the [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") constructor. ``` >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.srs.srid 4326 >>> rst.srs = 3086 >>> rst.srs.srid 3086 ``` - srid[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L374)[¶](#django.contrib.gis.gdal.GDALRaster.srid "Link to this definition") The Spatial Reference System Identifier (SRID) of the raster. This property is a shortcut to getting or setting the SRID through the [`srs`](#django.contrib.gis.gdal.GDALRaster.srs "django.contrib.gis.gdal.GDALRaster.srs") attribute. ``` >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.srid 4326 >>> rst.srid = 3086 >>> rst.srid 3086 >>> rst.srs.srid # This is equivalent 3086 ``` * geotransform[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L393)[¶](#django.contrib.gis.gdal.GDALRaster.geotransform "Link to this definition") The affine transformation matrix used to georeference the source, as a tuple of six coefficients which map pixel/line coordinates into georeferenced space using the following relationship: ``` Xgeo = GT(0) + Xpixel * GT(1) + Yline * GT(2) Ygeo = GT(3) + Xpixel * GT(4) + Yline * GT(5) ``` The same values can be retrieved by accessing the [`origin`](#django.contrib.gis.gdal.GDALRaster.origin "django.contrib.gis.gdal.GDALRaster.origin") (indices 0 and 3), [`scale`](#django.contrib.gis.gdal.GDALRaster.scale "django.contrib.gis.gdal.GDALRaster.scale") (indices 1 and 5) and [`skew`](#django.contrib.gis.gdal.GDALRaster.skew "django.contrib.gis.gdal.GDALRaster.skew") (indices 2 and 4) properties. The default is `[0.0, 1.0, 0.0, 0.0, 0.0, -1.0]`. ``` >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.geotransform [0.0, 1.0, 0.0, 0.0, 0.0, -1.0] ``` - origin[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L403)[¶](#django.contrib.gis.gdal.GDALRaster.origin "Link to this definition") Coordinates of the top left origin of the raster in the spatial reference system of the source, as a point object with `x` and `y` members. ``` >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.origin [0.0, 0.0] >>> rst.origin.x = 1 >>> rst.origin [1.0, 0.0] ``` * scale[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L410)[¶](#django.contrib.gis.gdal.GDALRaster.scale "Link to this definition") Pixel width and height used for georeferencing the raster, as a point object with `x` and `y` members. See [`geotransform`](#django.contrib.gis.gdal.GDALRaster.geotransform "django.contrib.gis.gdal.GDALRaster.geotransform") for more information. ``` >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.scale [1.0, -1.0] >>> rst.scale.x = 2 >>> rst.scale [2.0, -1.0] ``` - skew[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L417)[¶](#django.contrib.gis.gdal.GDALRaster.skew "Link to this definition") Skew coefficients used to georeference the raster, as a point object with `x` and `y` members. In case of north up images, these coefficients are both `0`. ``` >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.skew [0.0, 0.0] >>> rst.skew.x = 3 >>> rst.skew [3.0, 0.0] ``` * extent[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L424)[¶](#django.contrib.gis.gdal.GDALRaster.extent "Link to this definition") Extent (boundary values) of the raster source, as a 4-tuple `(xmin, ymin, xmax, ymax)` in the spatial reference system of the source. ``` >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.extent (0.0, -20.0, 10.0, 0.0) >>> rst.origin.x = 100 >>> rst.extent (100.0, -20.0, 110.0, 0.0) ``` - bands[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L440)[¶](#django.contrib.gis.gdal.GDALRaster.bands "Link to this definition") List of all bands of the source, as [`GDALBand`](#django.contrib.gis.gdal.GDALBand "django.contrib.gis.gdal.GDALBand") instances. ``` >>> rst = GDALRaster( ... { ... "width": 1, ... "height": 2, ... "srid": 4326, ... "bands": [{"data": [0, 1]}, {"data": [2, 3]}], ... } ... ) >>> len(rst.bands) 2 >>> rst.bands[1].data() array([[ 2., 3.]], dtype=float32) ``` * warp(*ds\_input*, *resampling='NearestNeighbour'*, *max\_error=0.0*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L443)[¶](#django.contrib.gis.gdal.GDALRaster.warp "Link to this definition") Returns a warped version of this raster. The warping parameters can be specified through the `ds_input` argument. The use of `ds_input` is analogous to the corresponding argument of the class constructor. It is a dictionary with the characteristics of the target raster. Allowed dictionary key values are width, height, SRID, origin, scale, skew, datatype, driver, and name (filename). By default, the warp functions keeps most parameters equal to the values of the original source raster, so only parameters that should be changed need to be specified. Note that this includes the driver, so for file-based rasters the warp function will create a new raster on disk. The only parameter that is set differently from the source raster is the name. The default value of the raster name is the name of the source raster appended with `'_copy' + source_driver_name`. For file-based rasters it is recommended to provide the file path of the target raster. The resampling algorithm used for warping can be specified with the `resampling` argument. The default is `NearestNeighbor`, and the other allowed values are `Bilinear`, `Cubic`, `CubicSpline`, `Lanczos`, `Average`, and `Mode`. The `max_error` argument can be used to specify the maximum error measured in input pixels that is allowed in approximating the transformation. The default is 0.0 for exact calculations. For users familiar with `GDAL`, this function has a similar functionality to the `gdalwarp` command-line utility. For example, the warp function can be used for aggregating a raster to the double of its original pixel scale: ``` >>> rst = GDALRaster( ... { ... "width": 6, ... "height": 6, ... "srid": 3086, ... "origin": [500000, 400000], ... "scale": [100, -100], ... "bands": [{"data": range(36), "nodata_value": 99}], ... } ... ) >>> target = rst.warp({"scale": [200, -200], "width": 3, "height": 3}) >>> target.bands[0].data() array([[ 7., 9., 11.], [ 19., 21., 23.], [ 31., 33., 35.]], dtype=float32) ``` - transform(*srs*, *driver=None*, *name=None*, *resampling='NearestNeighbour'*, *max\_error=0.0*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L526)[¶](#django.contrib.gis.gdal.GDALRaster.transform "Link to this definition") Transforms this raster to a different spatial reference system (`srs`), which may be a [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") object, or any other input accepted by [`SpatialReference`](#django.contrib.gis.gdal.SpatialReference "django.contrib.gis.gdal.SpatialReference") (including spatial reference WKT and PROJ strings, or an integer SRID). It calculates the bounds and scale of the current raster in the new spatial reference system and warps the raster using the [`warp`](#django.contrib.gis.gdal.GDALRaster.warp "django.contrib.gis.gdal.GDALRaster.warp") function. By default, the driver of the source raster is used and the name of the raster is the original name appended with `'_copy' + source_driver_name`. A different driver or name can be specified with the `driver` and `name` arguments. The default resampling algorithm is `NearestNeighbour` but can be changed using the `resampling` argument. The default maximum allowed error for resampling is 0.0 and can be changed using the `max_error` argument. Consult the [`warp`](#django.contrib.gis.gdal.GDALRaster.warp "django.contrib.gis.gdal.GDALRaster.warp") documentation for detail on those arguments. ``` >>> rst = GDALRaster( ... { ... "width": 6, ... "height": 6, ... "srid": 3086, ... "origin": [500000, 400000], ... "scale": [100, -100], ... "bands": [{"data": range(36), "nodata_value": 99}], ... } ... ) >>> target_srs = SpatialReference(4326) >>> target = rst.transform(target_srs) >>> target.origin [-82.98492744885776, 27.601924753080144] ``` * info[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L580)[¶](#django.contrib.gis.gdal.GDALRaster.info "Link to this definition") Returns a string with a summary of the raster. This is equivalent to the [gdalinfo](https://gdal.org/programs/gdalinfo.html) command line utility. - metadata[¶](#django.contrib.gis.gdal.GDALRaster.metadata "Link to this definition") The metadata of this raster, represented as a nested dictionary. The first-level key is the metadata domain. The second-level contains the metadata item names and values from each domain. To set or update a metadata item, pass the corresponding metadata item to the method using the nested structure described above. Only keys that are in the specified dictionary are updated; the rest of the metadata remains unchanged. To remove a metadata item, use `None` as the metadata value. ``` >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326}) >>> rst.metadata {} >>> rst.metadata = {"DEFAULT": {"OWNER": "Django", "VERSION": "1.0"}} >>> rst.metadata {'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}} >>> rst.metadata = {"DEFAULT": {"OWNER": None, "VERSION": "2.0"}} >>> rst.metadata {'DEFAULT': {'VERSION': '2.0'}} ``` * vsi\_buffer[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L285)[¶](#django.contrib.gis.gdal.GDALRaster.vsi_buffer "Link to this definition") A `bytes` representation of this raster. Returns `None` for rasters that are not stored in GDAL’s in-memory virtual filesystem. - is\_vsi\_based[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/raster/source.py#L300)[¶](#django.contrib.gis.gdal.GDALRaster.is_vsi_based "Link to this definition") A boolean indicating if this raster is stored in GDAL’s virtual filesystem. ### `GDALBand`[¶](#gdalband "Link to this heading") * *class *GDALBand[¶](#django.contrib.gis.gdal.GDALBand "Link to this definition") `GDALBand` instances are not created explicitly, but rather obtained from a [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") object, through its [`bands`](#django.contrib.gis.gdal.GDALRaster.bands "django.contrib.gis.gdal.GDALRaster.bands") attribute. The GDALBands contain the actual pixel values of the raster. * description[¶](#django.contrib.gis.gdal.GDALBand.description "Link to this definition") The name or description of the band, if any. - width[¶](#django.contrib.gis.gdal.GDALBand.width "Link to this definition") The width of the band in pixels (X-axis). * height[¶](#django.contrib.gis.gdal.GDALBand.height "Link to this definition") The height of the band in pixels (Y-axis). - pixel\_count[¶](#django.contrib.gis.gdal.GDALBand.pixel_count "Link to this definition") The total number of pixels in this band. Is equal to `width * height`. * statistics(*refresh=False*, *approximate=False*)[¶](#django.contrib.gis.gdal.GDALBand.statistics "Link to this definition") Compute statistics on the pixel values of this band. The return value is a tuple with the following structure: `(minimum, maximum, mean, standard deviation)`. If the `approximate` argument is set to `True`, the statistics may be computed based on overviews or a subset of image tiles. If the `refresh` argument is set to `True`, the statistics will be computed from the data directly, and the cache will be updated with the result. If a persistent cache value is found, that value is returned. For raster formats using Persistent Auxiliary Metadata (PAM) services, the statistics might be cached in an auxiliary file. In some cases this metadata might be out of sync with the pixel values or cause values from a previous call to be returned which don’t reflect the value of the `approximate` argument. In such cases, use the `refresh` argument to get updated values and store them in the cache. For empty bands (where all pixel values are “no data”), all statistics are returned as `None`. The statistics can also be retrieved directly by accessing the [`min`](#django.contrib.gis.gdal.GDALBand.min "django.contrib.gis.gdal.GDALBand.min"), [`max`](#django.contrib.gis.gdal.GDALBand.max "django.contrib.gis.gdal.GDALBand.max"), [`mean`](#django.contrib.gis.gdal.GDALBand.mean "django.contrib.gis.gdal.GDALBand.mean"), and [`std`](#django.contrib.gis.gdal.GDALBand.std "django.contrib.gis.gdal.GDALBand.std") properties. - min[¶](#django.contrib.gis.gdal.GDALBand.min "Link to this definition") The minimum pixel value of the band (excluding the “no data” value). * max[¶](#django.contrib.gis.gdal.GDALBand.max "Link to this definition") The maximum pixel value of the band (excluding the “no data” value). - mean[¶](#django.contrib.gis.gdal.GDALBand.mean "Link to this definition") The mean of all pixel values of the band (excluding the “no data” value). * std[¶](#django.contrib.gis.gdal.GDALBand.std "Link to this definition") The standard deviation of all pixel values of the band (excluding the “no data” value). - nodata\_value[¶](#django.contrib.gis.gdal.GDALBand.nodata_value "Link to this definition") The “no data” value for a band is generally a special marker value used to mark pixels that are not valid data. Such pixels should generally not be displayed, nor contribute to analysis operations. To delete an existing “no data” value, set this property to `None`. * datatype(*as\_string=False*)[¶](#django.contrib.gis.gdal.GDALBand.datatype "Link to this definition") The data type contained in the band, as an integer constant between 0 (Unknown) and 14. If `as_string` is `True`, the data type is returned as a string. Check out the “GDAL Pixel Type” column in the [datatype value table](#gdal-raster-datatype) for possible values. - color\_interp(*as\_string=False*)[¶](#django.contrib.gis.gdal.GDALBand.color_interp "Link to this definition") The color interpretation for the band, as an integer between 0 and 16. If `as_string` is `True`, the data type is returned as a string with the following possible values: `GCI_Undefined`, `GCI_GrayIndex`, `GCI_PaletteIndex`, `GCI_RedBand`, `GCI_GreenBand`, `GCI_BlueBand`, `GCI_AlphaBand`, `GCI_HueBand`, `GCI_SaturationBand`, `GCI_LightnessBand`, `GCI_CyanBand`, `GCI_MagentaBand`, `GCI_YellowBand`, `GCI_BlackBand`, `GCI_YCbCr_YBand`, `GCI_YCbCr_CbBand`, and `GCI_YCbCr_CrBand`. `GCI_YCbCr_CrBand` also represents `GCI_Max` because both correspond to the integer 16, but only `GCI_YCbCr_CrBand` is returned as a string. * data(*data=None*, *offset=None*, *size=None*, *shape=None*)[¶](#django.contrib.gis.gdal.GDALBand.data "Link to this definition") The accessor to the pixel values of the `GDALBand`. Returns the complete data array if no parameters are provided. A subset of the pixel array can be requested by specifying an offset and block size as tuples. If NumPy is available, the data is returned as NumPy array. For performance reasons, it is highly recommended to use NumPy. Data is written to the `GDALBand` if the `data` parameter is provided. The input can be of one of the following types - packed string, buffer, list, array, and NumPy array. The number of items in the input should normally correspond to the total number of pixels in the band, or to the number of pixels for a specific block of pixel values if the `offset` and `size` parameters are provided. If the number of items in the input is different from the target pixel block, the `shape` parameter must be specified. The shape is a tuple that specifies the width and height of the input data in pixels. The data is then replicated to update the pixel values of the selected block. This is useful to fill an entire band with a single value, for instance. For example: ``` >>> rst = GDALRaster( ... {"width": 4, "height": 4, "srid": 4326, "datatype": 1, "nr_of_bands": 1} ... ) >>> bnd = rst.bands[0] >>> bnd.data(range(16)) >>> bnd.data() array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]], dtype=int8) >>> bnd.data(offset=(1, 1), size=(2, 2)) array([[ 5, 6], [ 9, 10]], dtype=int8) >>> bnd.data(data=[-1, -2, -3, -4], offset=(1, 1), size=(2, 2)) >>> bnd.data() array([[ 0, 1, 2, 3], [ 4, -1, -2, 7], [ 8, -3, -4, 11], [12, 13, 14, 15]], dtype=int8) >>> bnd.data(data="\x9d\xa8\xb3\xbe", offset=(1, 1), size=(2, 2)) >>> bnd.data() array([[ 0, 1, 2, 3], [ 4, -99, -88, 7], [ 8, -77, -66, 11], [ 12, 13, 14, 15]], dtype=int8) >>> bnd.data([1], shape=(1, 1)) >>> bnd.data() array([[1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1]], dtype=uint8) >>> bnd.data(range(4), shape=(1, 4)) array([[0, 0, 0, 0], [1, 1, 1, 1], [2, 2, 2, 2], [3, 3, 3, 3]], dtype=uint8) ``` - metadata[¶](#django.contrib.gis.gdal.GDALBand.metadata "Link to this definition") The metadata of this band. The functionality is identical to [`GDALRaster.metadata`](#django.contrib.gis.gdal.GDALRaster.metadata "django.contrib.gis.gdal.GDALRaster.metadata"). ### Creating rasters from data[¶](#creating-rasters-from-data "Link to this heading") This section describes how to create rasters from scratch using the `ds_input` parameter. A new raster is created when a `dict` is passed to the [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") constructor. The dictionary contains defining parameters of the new raster, such as the origin, size, or spatial reference system. The dictionary can also contain pixel data and information about the format of the new raster. The resulting raster can therefore be file-based or memory-based, depending on the driver specified. There’s no standard for describing raster data in a dictionary or JSON flavor. The definition of the dictionary input to the [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") class is therefore specific to Django. It’s inspired by the [geojson](https://geojson.org/) format, but the `geojson` standard is currently limited to vector formats. Examples of using the different keys when creating rasters can be found in the documentation of the corresponding attributes and methods of the [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") and [`GDALBand`](#django.contrib.gis.gdal.GDALBand "django.contrib.gis.gdal.GDALBand") classes. #### The `ds_input` dictionary[¶](#the-ds-input-dictionary "Link to this heading") Only a few keys are required in the `ds_input` dictionary to create a raster: `width`, `height`, and `srid`. All other parameters have default values (see the table below). The list of keys that can be passed in the `ds_input` dictionary is closely related but not identical to the [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") properties. Many of the parameters are mapped directly to those properties; the others are described below. The following table describes all keys that can be set in the `ds_input` dictionary. | Key | Default | Usage | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `srid` | required | Mapped to the [`srid`](#django.contrib.gis.gdal.GDALRaster.srid "django.contrib.gis.gdal.GDALRaster.srid") attribute | | `width` | required | Mapped to the [`width`](#django.contrib.gis.gdal.GDALRaster.width "django.contrib.gis.gdal.GDALRaster.width") attribute | | `height` | required | Mapped to the [`height`](#django.contrib.gis.gdal.GDALRaster.height "django.contrib.gis.gdal.GDALRaster.height") attribute | | `driver` | `MEM` | Mapped to the [`driver`](#django.contrib.gis.gdal.GDALRaster.driver "django.contrib.gis.gdal.GDALRaster.driver") attribute | | `name` | `''` | See below | | `origin` | `0` | Mapped to the [`origin`](#django.contrib.gis.gdal.GDALRaster.origin "django.contrib.gis.gdal.GDALRaster.origin") attribute | | `scale` | `0` | Mapped to the [`scale`](#django.contrib.gis.gdal.GDALRaster.scale "django.contrib.gis.gdal.GDALRaster.scale") attribute | | `skew` | `0` | Mapped to the [`width`](#django.contrib.gis.gdal.GDALRaster.width "django.contrib.gis.gdal.GDALRaster.width") attribute | | `bands` | `[]` | See below | | `nr_of_bands` | `0` | See below | | `datatype` | `6` | See below | | `papsz_options` | `{}` | See below | * name String representing the name of the raster. When creating a file-based raster, this parameter must be the file path for the new raster. If the name starts with `/vsimem/`, the raster is created in GDAL’s virtual filesystem. - datatype Integer representing the data type for all the bands. Defaults to `6` (Float32). All bands of a new raster are required to have the same datatype. The value mapping is: | Value | GDAL Pixel Type | Description | | ----- | --------------- | ----------------------------------- | | 1 | GDT\_Byte | 8 bit unsigned integer | | 2 | GDT\_UInt16 | 16 bit unsigned integer | | 3 | GDT\_Int16 | 16 bit signed integer | | 4 | GDT\_UInt32 | 32 bit unsigned integer | | 5 | GDT\_Int32 | 32 bit signed integer | | 6 | GDT\_Float32 | 32 bit floating point | | 7 | GDT\_Float64 | 64 bit floating point | | 12 | GDT\_UInt64 | 64 bit unsigned integer (GDAL 3.5+) | | 13 | GDT\_Int64 | 64 bit signed integer (GDAL 3.5+) | | 14 | GDT\_Int8 | 8 bit signed integer (GDAL 3.7+) | * nr\_of\_bands Integer representing the number of bands of the raster. A raster can be created without passing band data upon creation. If the number of bands isn’t specified, it’s automatically calculated from the length of the `bands` input. The number of bands can’t be changed after creation. - bands A list of `band_input` dictionaries with band input data. The resulting band indices are the same as in the list provided. The definition of the band input dictionary is given below. If band data isn’t provided, the raster bands values are instantiated as an array of zeros and the “no data” value is set to `None`. * papsz\_options A dictionary with raster creation options. The key-value pairs of the input dictionary are passed to the driver on creation of the raster. The available options are driver-specific and are described in the documentation of each driver. The values in the dictionary are not case-sensitive and are automatically converted to the correct string format upon creation. The following example uses some of the options available for the [GTiff driver](https://gdal.org/drivers/raster/gtiff.html). The result is a compressed raster with an internal tiling scheme. The internal tiles have a block size of 23 by 23: ``` >>> GDALRaster( ... { ... "driver": "GTiff", ... "name": "/path/to/new/file.tif", ... "srid": 4326, ... "width": 255, ... "height": 255, ... "nr_of_bands": 1, ... "papsz_options": { ... "compress": "packbits", ... "tiled": "yes", ... "blockxsize": 23, ... "blockysize": 23, ... }, ... } ... ) ``` #### The `band_input` dictionary[¶](#the-band-input-dictionary "Link to this heading") The `bands` key in the `ds_input` dictionary is a list of `band_input` dictionaries. Each `band_input` dictionary can contain pixel values and the “no data” value to be set on the bands of the new raster. The data array can have the full size of the new raster or be smaller. For arrays that are smaller than the full raster, the `size`, `shape`, and `offset` keys control the pixel values. The corresponding keys are passed to the [`data()`](#django.contrib.gis.gdal.GDALBand.data "django.contrib.gis.gdal.GDALBand.data") method. Their functionality is the same as setting the band data with that method. The following table describes the keys that can be used. | Key | Default | Usage | | -------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `nodata_value` | `None` | Mapped to the [`nodata_value`](#django.contrib.gis.gdal.GDALBand.nodata_value "django.contrib.gis.gdal.GDALBand.nodata_value") attribute | | `data` | Same as `nodata_value` or `0` | Passed to the [`data()`](#django.contrib.gis.gdal.GDALBand.data "django.contrib.gis.gdal.GDALBand.data") method | | `size` | `(with, height)` of raster | Passed to the [`data()`](#django.contrib.gis.gdal.GDALBand.data "django.contrib.gis.gdal.GDALBand.data") method | | `shape` | Same as size | Passed to the [`data()`](#django.contrib.gis.gdal.GDALBand.data "django.contrib.gis.gdal.GDALBand.data") method | | `offset` | `(0, 0)` | Passed to the [`data()`](#django.contrib.gis.gdal.GDALBand.data "django.contrib.gis.gdal.GDALBand.data") method | ### Using GDAL’s Virtual Filesystem[¶](#using-gdal-s-virtual-filesystem "Link to this heading") GDAL can access files stored in the filesystem, but also supports virtual filesystems to abstract accessing other kind of files, such as compressed, encrypted, or remote files. #### Using memory-based Virtual Filesystem[¶](#using-memory-based-virtual-filesystem "Link to this heading") GDAL has an internal memory-based filesystem, which allows treating blocks of memory as files. It can be used to read and write [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") objects to and from binary file buffers. This is useful in web contexts where rasters might be obtained as a buffer from a remote storage or returned from a view without being written to disk. [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") objects are created in the virtual filesystem when a `bytes` object is provided as input, or when the file path starts with `/vsimem/`. Input provided as `bytes` has to be a full binary representation of a file. For instance: ``` # Read a raster as a file object from a remote source. >>> from urllib.request import urlopen >>> dat = urlopen("https://example.com/raster.tif").read() # Instantiate a raster from the bytes object. >>> rst = GDALRaster(dat) # The name starts with /vsimem/, indicating that the raster lives in the # virtual filesystem. >>> rst.name '/vsimem/da300bdb-129d-49a8-b336-e410a9428dad' ``` To create a new virtual file-based raster from scratch, use the `ds_input` dictionary representation and provide a `name` argument that starts with `/vsimem/` (for detail of the dictionary representation, see [Creating rasters from data](#gdal-raster-ds-input)). For virtual file-based rasters, the [`vsi_buffer`](#django.contrib.gis.gdal.GDALRaster.vsi_buffer "django.contrib.gis.gdal.GDALRaster.vsi_buffer") attribute returns the `bytes` representation of the raster. Here’s how to create a raster and return it as a file in an [`HttpResponse`](../../../request-response/#django.http.HttpResponse "django.http.HttpResponse"): ``` >>> from django.http import HttpResponse >>> rst = GDALRaster( ... { ... "name": "/vsimem/temporarymemfile", ... "driver": "tif", ... "width": 6, ... "height": 6, ... "srid": 3086, ... "origin": [500000, 400000], ... "scale": [100, -100], ... "bands": [{"data": range(36), "nodata_value": 99}], ... } ... ) >>> HttpResponse(rast.vsi_buffer, "image/tiff") ``` Warning The memory-based virtual filesystem doesn’t make untrusted raster data safe. Raster data may reference local or remote resources, for example through a VRT source, causing GDAL to access files or make network requests. Only instantiate [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") from trusted input. #### Using other Virtual Filesystems[¶](#using-other-virtual-filesystems "Link to this heading") Depending on the local build of GDAL other virtual filesystems may be supported. You can use them by prepending the provided path with the appropriate `/vsi*/` prefix. See the [GDAL Virtual Filesystems documentation](https://gdal.org/user/virtual_file_systems.html) for more details. Warning Rasters with names starting with `/vsi*/` will be treated as rasters from the GDAL virtual filesystems. Django doesn’t perform any extra validation. ##### Compressed rasters[¶](#compressed-rasters "Link to this heading") Instead of decompressing the file and instantiating the resulting raster, GDAL can directly access compressed files using the `/vsizip/`, `/vsigzip/`, or `/vsitar/` virtual filesystems: ``` >>> from django.contrib.gis.gdal import GDALRaster >>> rst = GDALRaster("/vsizip/path/to/your/file.zip/path/to/raster.tif") >>> rst = GDALRaster("/vsigzip/path/to/your/file.gz") >>> rst = GDALRaster("/vsitar/path/to/your/file.tar/path/to/raster.tif") ``` ##### Network rasters[¶](#network-rasters "Link to this heading") GDAL can support online resources and storage providers transparently. As long as it’s built with such capabilities. To access a public raster file with no authentication, you can use `/vsicurl/`: ``` >>> from django.contrib.gis.gdal import GDALRaster >>> rst = GDALRaster("/vsicurl/https://example.com/raster.tif") >>> rst.name '/vsicurl/https://example.com/raster.tif' ``` For commercial storage providers (e.g. `/vsis3/`) the system should be previously configured for authentication and possibly other settings (see the [GDAL Virtual Filesystems documentation](https://gdal.org/user/virtual_file_systems.html) for available options). #### Security considerations[¶](#security-considerations "Link to this heading") Since [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") always opens new rasters in write mode, it is essential to prevent instantiating one from untrusted input. Otherwise, an attacker might gain the ability to write a file or make a network request. To mitigate this, [spatial lookups](../db-api/#spatial-lookups-intro) prevent `bytes`, `str`, [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)"), and `dict` values from reaching [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster") altogether. To use these types with lookups, wrap them explicitly with [`GDALRaster`](#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster"), indicating that the value is trusted. This protection applies only to spatial lookups. Assigning a `dict` or `bytes` value to a [`RasterField`](../model-api/#django.contrib.gis.db.models.RasterField "django.contrib.gis.db.models.RasterField") will still open a new raster, and assigning a `str` or `Path` will still fetch and open the referenced raster. When validating geometry inputs, the [`GeometryField`](../forms-api/#django.contrib.gis.forms.GeometryField "django.contrib.gis.forms.GeometryField") form field will reject raster values. When validating raster inputs, you should write custom validation. For defense-in-depth strategies for limiting the available raster drivers, see [GDAL security considerations](https://gdal.org/user/security.html). ## Settings[¶](#settings "Link to this heading") ### `GDAL_LIBRARY_PATH`[¶](#gdal-library-path "Link to this heading") A string specifying the location of the GDAL library. Typically, this setting is only used if the GDAL library is in a non-standard location (e.g., `/home/john/lib/libgdal.so`). ## Exceptions[¶](#exceptions "Link to this heading") * *exception *GDALException[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/error.py#L9)[¶](#django.contrib.gis.gdal.GDALException "Link to this definition") The base GDAL exception, indicating a GDAL-related error. - *exception *SRSException[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/gdal/error.py#L13)[¶](#django.contrib.gis.gdal.SRSException "Link to this definition") An exception raised when an error occurs when constructing or using a spatial reference system object. [**Back to Top](#top) ## Additional Information ### Support Django! * [Perfany GmbH donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [GDAL API](#) * [Overview](#overview) * [Sample Data](#sample-data) * [Vector Data Source Objects](#vector-data-source-objects) * [`DataSource`](#datasource) * [`Layer`](#layer) * [`Feature`](#feature) * [`Field`](#field) * [`Driver`](#driver) * [OGR Geometries](#ogr-geometries) * [`OGRGeometry`](#ogrgeometry) * [`OGRGeomType`](#ogrgeomtype) * [`Envelope`](#envelope) * [Coordinate System Objects](#coordinate-system-objects) * [`SpatialReference`](#spatialreference) * [`CoordTransform`](#coordtransform) * [Raster Data Objects](#raster-data-objects) * [`GDALRaster`](#gdalraster) * [`GDALBand`](#gdalband) * [Creating rasters from data](#creating-rasters-from-data) * [The `ds_input` dictionary](#the-ds-input-dictionary) * [The `band_input` dictionary](#the-band-input-dictionary) * [Using GDAL’s Virtual Filesystem](#using-gdal-s-virtual-filesystem) * [Using memory-based Virtual Filesystem](#using-memory-based-virtual-filesystem) * [Using other Virtual Filesystems](#using-other-virtual-filesystems) * [Compressed rasters](#compressed-rasters) * [Network rasters](#network-rasters) * [Security considerations](#security-considerations) * [Settings](#settings) * [`GDAL_LIBRARY_PATH`](#gdal-library-path) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.8.4/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.8.4/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.8.4/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.8.4/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.8.4/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.8.4/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.8.4/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.8.4/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.8.4/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.8.4/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.8.4/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.8.4/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.8.4/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.8.4/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.8.4/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.8.4/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.8.4/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.8.4/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.8.4/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.8.4/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.8.4/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.8.4/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.8.4/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.8.4/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.8.4/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.8.4/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.8.4/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.8.4/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.8.4/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.8.4/) - [**](#top) # Django 1.8.4 release notes[¶](#django-1-8-4-release-notes "Link to this heading") *August 18, 2015* Django 1.8.4 fixes a security issue and several bugs in 1.8.3. ## Denial-of-service possibility in `logout()` view by filling session store[¶](#denial-of-service-possibility-in-logout-view-by-filling-session-store "Link to this heading") Previously, a session could be created when anonymously accessing the `django.contrib.auth.views.logout()` view (provided it wasn’t decorated with [`login_required()`](../../topics/auth/default/#django.contrib.auth.decorators.login_required "django.contrib.auth.decorators.login_required") as done in the admin). This could allow an attacker to easily create many new session records by sending repeated requests, potentially filling up the session store or causing other users’ session records to be evicted. The [`SessionMiddleware`](../../ref/middleware/#django.contrib.sessions.middleware.SessionMiddleware "django.contrib.sessions.middleware.SessionMiddleware") has been modified to no longer create empty session records, including when [`SESSION_SAVE_EVERY_REQUEST`](../../ref/settings/#std-setting-SESSION_SAVE_EVERY_REQUEST) is active. ## Bugfixes[¶](#bugfixes "Link to this heading") * Added the ability to serialize values from the newly added [`UUIDField`](../../ref/models/fields/#django.db.models.UUIDField "django.db.models.UUIDField") ([#25019](https://code.djangoproject.com/ticket/25019)). * Added a system check warning if the old `TEMPLATE_*` settings are defined in addition to the new `TEMPLATES` setting. * Fixed `QuerySet.raw()` so `InvalidQuery` is not raised when using the `db_column` name of a `ForeignKey` field with `primary_key=True` ([#12768](https://code.djangoproject.com/ticket/12768)). * Prevented an exception in `TestCase.setUpTestData()` from leaking the transaction ([#25176](https://code.djangoproject.com/ticket/25176)). * Fixed `has_changed()` method in `contrib.postgres.forms.HStoreField` ([#25215](https://code.djangoproject.com/ticket/25215), [#25233](https://code.djangoproject.com/ticket/25233)). * Fixed the recording of squashed migrations when running the `migrate` command ([#25231](https://code.djangoproject.com/ticket/25231)). * Moved the [unsaved model instance assignment data loss check](../1.8/#unsaved-model-instance-check-18) to `Model.save()` to allow easier usage of in-memory models ([#25160](https://code.djangoproject.com/ticket/25160)). * Prevented `varchar_patterns_ops` and `text_patterns_ops` indexes for `ArrayField` ([#25180](https://code.djangoproject.com/ticket/25180)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Rafael Tardivo donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.8.4 release notes](#) * [Denial-of-service possibility in `logout()` view by filling session store](#denial-of-service-possibility-in-logout-view-by-filling-session-store) ---- url: https://docs.djangoproject.com/en/6.1/releases/2.1.3/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/2.1.3/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/2.1.3/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/2.1.3/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/2.1.3/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/2.1.3/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/2.1.3/) - [it](https://docs.djangoproject.com/it/6.1/releases/2.1.3/) - [id](https://docs.djangoproject.com/id/6.1/releases/2.1.3/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/2.1.3/) - [es](https://docs.djangoproject.com/es/6.1/releases/2.1.3/) - [el](https://docs.djangoproject.com/el/6.1/releases/2.1.3/) * * [dev](https://docs.djangoproject.com/en/dev/releases/2.1.3/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/2.1.3/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/2.1.3/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/2.1.3/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/2.1.3/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/2.1.3/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/2.1.3/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/2.1.3/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/2.1.3/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/2.1.3/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/2.1.3/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/2.1.3/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/2.1.3/) - [**](#top) # Django 2.1.3 release notes[¶](#django-2-1-3-release-notes "Link to this heading") *November 1, 2018* Django 2.1.3 fixes several bugs in 2.1.2. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a regression in Django 2.0 where combining `Q` objects with `__in` lookups and lists crashed ([#29838](https://code.djangoproject.com/ticket/29838)). * Fixed a regression in Django 1.11 where `django-admin shell` may hang on startup ([#29774](https://code.djangoproject.com/ticket/29774)). * Fixed a regression in Django 2.0 where test databases aren’t reused with `manage.py test --keepdb` on MySQL ([#29827](https://code.djangoproject.com/ticket/29827)). * Fixed a regression where cached foreign keys that use `to_field` were incorrectly cleared in `Model.save()` ([#29896](https://code.djangoproject.com/ticket/29896)). * Fixed a regression in Django 2.0 where `FileSystemStorage` crashes with `FileExistsError` if concurrent saves try to create the same directory ([#29890](https://code.djangoproject.com/ticket/29890)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Andrew Pinkham donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 2.1.3 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.9.2/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.9.2/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.9.2/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.9.2/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.9.2/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.9.2/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.9.2/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.9.2/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.9.2/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.9.2/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.9.2/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.9.2/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.9.2/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.9.2/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.9.2/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.9.2/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.9.2/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.9.2/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.9.2/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.9.2/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.9.2/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.9.2/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.9.2/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.9.2/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.9.2/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.9.2/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.9.2/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.9.2/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.9.2/) - [**](#top) # Django 1.9.2 release notes[¶](#django-1-9-2-release-notes "Link to this heading") *February 1, 2016* Django 1.9.2 fixes a security regression in 1.9 and several bugs in 1.9.1. It also makes a small backwards incompatible change that hopefully doesn’t affect any users. ## Security issue: User with “change” but not “add” permission can create objects for `ModelAdmin`’s with `save_as=True`[¶](#security-issue-user-with-change-but-not-add-permission-can-create-objects-for-modeladmins-with-save-as-true "Link to this heading") If a `ModelAdmin` uses `save_as=True` (not the default), the admin provides an option when editing objects to “Save as new”. A regression in Django 1.9 prevented that form submission from raising a “Permission Denied” error for users without the “add” permission. ## Backwards incompatible change: `.py-tpl` files rewritten in project/app templates[¶](#backwards-incompatible-change-py-tpl-files-rewritten-in-project-app-templates "Link to this heading") The addition of some Django template language syntax to the default app template in Django 1.9 means those files now have some invalid Python syntax. This causes difficulties for packaging systems that unconditionally byte-compile `*.py` files. To remedy this, a `.py-tpl` suffix is now used for the project and app template files included in Django. The `.py-tpl` suffix is replaced with `.py` by the `startproject` and `startapp` commands. For example, a template with the filename `manage.py-tpl` will be created as `manage.py`. Please file a ticket if you have a custom project template containing `.py-tpl` files and find this behavior problematic. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a regression in `ConditionalGetMiddleware` causing `If-None-Match` checks to always return HTTP 200 ([#26024](https://code.djangoproject.com/ticket/26024)). * Fixed a regression that caused the “user-tools” items to display on the admin’s logout page ([#26035](https://code.djangoproject.com/ticket/26035)). * Fixed a crash in the translations system when the current language has no translations ([#26046](https://code.djangoproject.com/ticket/26046)). * Fixed a regression that caused the incorrect day to be selected when opening the admin calendar widget for timezones from GMT+0100 to GMT+1200 ([#24980](https://code.djangoproject.com/ticket/24980)). * Fixed a regression in the admin’s edit related model popup that caused an escaped value to be displayed in the select dropdown of the parent window ([#25997](https://code.djangoproject.com/ticket/25997)). * Fixed a regression in 1.8.8 causing incorrect index handling in migrations on PostgreSQL when adding `db_index=True` or `unique=True` to a `CharField` or `TextField` that already had the other specified, or when removing one of them from a field that had both, or when adding `unique=True` to a field already listed in `unique_together` ([#26034](https://code.djangoproject.com/ticket/26034)). * Fixed a regression where defining a relation on an abstract model’s field using a string model name without an app\_label no longer resolved that reference to the abstract model’s app if using that model in another application ([#25858](https://code.djangoproject.com/ticket/25858)). * Fixed a crash when destroying an existing test database on MySQL or PostgreSQL ([#26096](https://code.djangoproject.com/ticket/26096)). * Fixed CSRF cookie check on POST requests when `USE_X_FORWARDED_PORT=True` ([#26094](https://code.djangoproject.com/ticket/26094)). * Fixed a `QuerySet.order_by()` crash when ordering by a relational field of a `ManyToManyField` `through` model ([#26092](https://code.djangoproject.com/ticket/26092)). * Fixed a regression that caused an exception when making database queries on SQLite with more than 2000 parameters when [`DEBUG`](../../ref/settings/#std-setting-DEBUG) is `True` on distributions that increase the `SQLITE_MAX_VARIABLE_NUMBER` compile-time limit to over 2000, such as Debian ([#26063](https://code.djangoproject.com/ticket/26063)). * Fixed a crash when using a reverse `OneToOneField` in `ModelAdmin.readonly_fields` ([#26060](https://code.djangoproject.com/ticket/26060)). * Fixed a crash when calling the `migrate` command in a test case with the `available_apps` attribute pointing to an application with migrations disabled using the `MIGRATION_MODULES` setting ([#26135](https://code.djangoproject.com/ticket/26135)). * Restored the ability for testing and debugging tools to determine the template from which a node came from, even during template inheritance or inclusion. Prior to Django 1.9, debugging tools could access the template origin from the node via `Node.token.source[0]`. This was an undocumented, private API. The origin is now available directly on each node using the `Node.origin` attribute ([#25848](https://code.djangoproject.com/ticket/25848)). * Fixed a regression in Django 1.8.5 that broke copying a `SimpleLazyObject` with `copy.copy()` ([#26122](https://code.djangoproject.com/ticket/26122)). * Always included `geometry_field` in the GeoJSON serializer output regardless of the `fields` parameter ([#26138](https://code.djangoproject.com/ticket/26138)). * Fixed the `contrib.gis` map widgets when using `USE_THOUSAND_SEPARATOR=True` ([#20415](https://code.djangoproject.com/ticket/20415)). * Made invalid forms display the initial of values of their disabled fields ([#26129](https://code.djangoproject.com/ticket/26129)). [**Back to Top](#top) ## Additional Information ### Support Django! * [@crydotsnake donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.9.2 release notes](#) * [Security issue: User with “change” but not “add” permission can create objects for `ModelAdmin`’s with `save_as=True`](#security-issue-user-with-change-but-not-add-permission-can-create-objects-for-modeladmins-with-save-as-true) * [Backwards incompatible change: `.py-tpl` files rewritten in project/app templates](#backwards-incompatible-change-py-tpl-files-rewritten-in-project-app-templates) ---- url: https://docs.djangoproject.com/en/6.1/releases/3.2.3/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/3.2.3/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/3.2.3/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/3.2.3/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/3.2.3/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/3.2.3/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/3.2.3/) - [it](https://docs.djangoproject.com/it/6.1/releases/3.2.3/) - [id](https://docs.djangoproject.com/id/6.1/releases/3.2.3/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/3.2.3/) - [es](https://docs.djangoproject.com/es/6.1/releases/3.2.3/) - [el](https://docs.djangoproject.com/el/6.1/releases/3.2.3/) * * [dev](https://docs.djangoproject.com/en/dev/releases/3.2.3/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/3.2.3/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/3.2.3/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/3.2.3/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/3.2.3/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/3.2.3/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/3.2.3/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/3.2.3/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/3.2.3/) - [**](#top) # Django 3.2.3 release notes[¶](#django-3-2-3-release-notes "Link to this heading") *May 13, 2021* Django 3.2.3 fixes several bugs in 3.2.2. ## Bugfixes[¶](#bugfixes "Link to this heading") * Prepared for `mysqlclient` > 2.0.3 support ([#32732](https://code.djangoproject.com/ticket/32732)). * Fixed a regression in Django 3.2 that caused the incorrect filtering of querysets combined with the `|` operator ([#32717](https://code.djangoproject.com/ticket/32717)). * Fixed a regression in Django 3.2.1 where saving `FileField` would raise a `SuspiciousFileOperation` even when a custom [`upload_to`](../../ref/models/fields/#django.db.models.FileField.upload_to "django.db.models.FileField.upload_to") returns a valid file path ([#32718](https://code.djangoproject.com/ticket/32718)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Lambert Labs donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 3.2.3 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/intro/contributing/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/intro/contributing/) - [sv](https://docs.djangoproject.com/sv/6.1/intro/contributing/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/intro/contributing/) - [pl](https://docs.djangoproject.com/pl/6.1/intro/contributing/) - [ko](https://docs.djangoproject.com/ko/6.1/intro/contributing/) - [ja](https://docs.djangoproject.com/ja/6.1/intro/contributing/) - [it](https://docs.djangoproject.com/it/6.1/intro/contributing/) - [id](https://docs.djangoproject.com/id/6.1/intro/contributing/) - [fr](https://docs.djangoproject.com/fr/6.1/intro/contributing/) - [es](https://docs.djangoproject.com/es/6.1/intro/contributing/) - [el](https://docs.djangoproject.com/el/6.1/intro/contributing/) * * [dev](https://docs.djangoproject.com/en/dev/intro/contributing/) * [6.0](https://docs.djangoproject.com/en/6.0/intro/contributing/) * [5.2](https://docs.djangoproject.com/en/5.2/intro/contributing/) * [5.1](https://docs.djangoproject.com/en/5.1/intro/contributing/) * [5.0](https://docs.djangoproject.com/en/5.0/intro/contributing/) * [4.2](https://docs.djangoproject.com/en/4.2/intro/contributing/) * [4.1](https://docs.djangoproject.com/en/4.1/intro/contributing/) * [4.0](https://docs.djangoproject.com/en/4.0/intro/contributing/) * [3.2](https://docs.djangoproject.com/en/3.2/intro/contributing/) * [3.1](https://docs.djangoproject.com/en/3.1/intro/contributing/) * [3.0](https://docs.djangoproject.com/en/3.0/intro/contributing/) * [2.2](https://docs.djangoproject.com/en/2.2/intro/contributing/) * [2.1](https://docs.djangoproject.com/en/2.1/intro/contributing/) * [2.0](https://docs.djangoproject.com/en/2.0/intro/contributing/) * [1.11](https://docs.djangoproject.com/en/1.11/intro/contributing/) * [1.10](https://docs.djangoproject.com/en/1.10/intro/contributing/) * [1.9](https://docs.djangoproject.com/en/1.9/intro/contributing/) * [1.8](https://docs.djangoproject.com/en/1.8/intro/contributing/) - [**](#top) # Writing your first contribution for Django[¶](#writing-your-first-contribution-for-django "Link to this heading") ## Introduction[¶](#introduction "Link to this heading") Interested in giving back to the community a little? Maybe you’ve found a bug in Django that you’d like to see fixed, or maybe there’s a small feature you want added (but remember that proposals for new features should follow the [process for suggesting new features](../../internals/contributing/bugs-and-features/#requesting-features)). Contributing back to Django itself is the best way to see your own concerns addressed. This may seem daunting at first, but it’s a well-traveled path with documentation, tooling, and a community to support you. We’ll walk you through the entire process, so you can learn by example. ### Who’s this tutorial for?[¶](#who-s-this-tutorial-for "Link to this heading") See also If you are looking for a reference on the details of making code contributions, see the [Contributing code](../../internals/contributing/writing-code/) documentation. For this tutorial, we expect that you have at least a basic understanding of how Django works. This means you should be comfortable going through the existing tutorials on [writing your first Django app](../tutorial01/). In addition, you should have a good understanding of Python itself. But if you don’t, [Dive Into Python](https://diveintopython3.net/) is a fantastic (and free) online book for beginning Python programmers. Those of you who are unfamiliar with version control systems and Trac will find that this tutorial and its links include just enough information to get started. However, you’ll probably want to read some more about these different tools if you plan on contributing to Django regularly. For the most part though, this tutorial tries to explain as much as possible, so that it can be of use to the widest audience. Where to get help: If you’re having trouble going through this tutorial, please post a message on the [Django Forum](https://forum.djangoproject.com/) or drop by the [Django Discord server](https://chat.djangoproject.com) to chat with other Django users who might be able to help. ### What does this tutorial cover?[¶](#what-does-this-tutorial-cover "Link to this heading") We’ll be walking you through contributing to Django for the first time. By the end of this tutorial, you should have a basic understanding of both the tools and the processes involved. Specifically, we’ll be covering the following: * Installing Git. * Downloading a copy of Django’s development version. * Running Django’s test suite. * Writing a test for your changes. * Writing the code for your changes. * Testing your changes. * Submitting a pull request. * Where to look for more information. Once you’re done with the tutorial, you can look through the rest of [Django’s documentation on contributing](../../internals/contributing/). It contains lots of great information and is a must-read for anyone who’d like to become a regular contributor to Django. If you’ve got questions, it’s probably got the answers. For Windows users See [Install Python](../../howto/windows/#install-python-windows) on Windows docs for additional guidance. ## Code of Conduct[¶](#code-of-conduct "Link to this heading") As a contributor, you can help us keep the Django community open and inclusive. Please read and follow our [Code of Conduct](https://www.djangoproject.com/conduct/). ## Installing Git[¶](#installing-git "Link to this heading") For this tutorial, you’ll need Git installed to download the current development version of Django and to generate a branch for the changes you make. To check whether or not you have Git installed, enter `git` into the command line. If you get messages saying that this command could not be found, you’ll have to download and install it, see [Git’s download page](https://git-scm.com/download). If you’re not that familiar with Git, you can always find out more about its commands (once it’s installed) by typing `git help` into the command line. ## Getting a copy of Django’s development version[¶](#getting-a-copy-of-django-s-development-version "Link to this heading") The first step to contributing to Django is to get a copy of the source code. First, [fork Django on GitHub](https://github.com/django/django/fork). Then, from the command line, use the `cd` command to navigate to the directory where you’ll want your local copy of Django to live. Download the Django source code repository using the following command: /  ``` $ git clone https://github.com/YourGitHubName/django.git ``` ** ``` ...\> git clone https://github.com/YourGitHubName/django.git ``` ** Low bandwidth connection? You can add the `--depth 1` argument to `git clone` to skip downloading all of Django’s commit history, which reduces data transfer from \~250 MB to \~70 MB. Now that you have a local copy of Django, you can install it just like you would install any package using `pip`. The most convenient way to do so is by using a *virtual environment*, which is a feature built into Python that allows you to keep a separate directory of installed packages for each of your projects so that they don’t interfere with each other. It’s a good idea to keep all your virtual environments in one place, for example in `.virtualenvs/` in your home directory. Create a new virtual environment by running: /  ``` $ python3 -m venv ~/.virtualenvs/djangodev ``` ** ``` ...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev ``` ** The path is where the new environment will be saved on your computer. The final step in setting up your virtual environment is to activate it: ``` $ source ~/.virtualenvs/djangodev/bin/activate ``` If the `source` command is not available, you can try using a dot instead: ``` $ . ~/.virtualenvs/djangodev/bin/activate ``` You have to activate the virtual environment whenever you open a new terminal window. For Windows users To activate your virtual environment on Windows, run: ``` ...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat ``` The name of the currently activated virtual environment is displayed on the command line to help you keep track of which one you are using. Anything you install through `pip` while this name is displayed will be installed in that virtual environment, isolated from other environments and system-wide packages. Go ahead and install the previously cloned copy of Django: /  ``` $ python -m pip install -e /path/to/your/local/clone/django/ ``` ** ``` ...\> py -m pip install -e \path\to\your\local\clone\django\ ``` ** The installed version of Django is now pointing at your local copy by installing in editable mode. You will immediately see any changes you make to it, which is of great help when testing your first contribution. ## Running Django’s test suite for the first time[¶](#running-django-s-test-suite-for-the-first-time "Link to this heading") When contributing to Django it’s very important that your code changes don’t introduce bugs into other areas of Django. One way to check that Django still works after you make your changes is by running Django’s test suite. If all the tests still pass, then you can be reasonably sure that your changes work and haven’t broken other parts of Django. If you’ve never run Django’s test suite before, it’s a good idea to run it once beforehand to get familiar with its output. Before running the test suite, enter the Django `tests/` directory using the `cd tests` command, and install test dependencies by running: /  ``` $ python -m pip install -r requirements/py3.txt ``` ** ``` ...\> py -m pip install -r requirements\py3.txt ``` ** If you encounter an error during the installation, your system might be missing a dependency for one or more of the Python packages. Consult the failing package’s documentation or search the web with the error message that you encounter. Now we are ready to run the test suite: /  ``` $ ./runtests.py ``` ** ``` ...\> runtests.py ``` ** Now sit back and relax. Django’s entire test suite has thousands of tests, and it takes at least a few minutes to run, depending on the speed of your computer. While Django’s test suite is running, you’ll see a stream of characters representing the status of each test as it completes. `E` indicates that an error was raised during a test, and `F` indicates that a test’s assertions failed. Both of these are considered to be test failures. Meanwhile, `x` and `s` indicate expected failures and skipped tests, respectively. Dots indicate passing tests. Skipped tests are typically due to missing external libraries required to run the test; see [Running all the tests](../../internals/contributing/writing-code/unit-tests/#running-unit-tests-dependencies) for a list of dependencies and be sure to install any for tests related to the changes you are making (we won’t need any for this tutorial). Some tests are specific to a particular database backend and will be skipped if not testing with that backend. SQLite is the database backend for the default settings. To run the tests using a different backend, see [Using another settings module](../../internals/contributing/writing-code/unit-tests/#running-unit-tests-settings). Once the tests complete, you should be greeted with a message informing you whether the test suite passed or failed. Since you haven’t yet made any changes to Django’s code, the entire test suite **should** pass. If you get failures or errors make sure you’ve followed all of the previous steps properly. See [Running the unit tests](../../internals/contributing/writing-code/unit-tests/#running-unit-tests) for more information. Note that the latest Django “main” branch may not always be stable. When developing against “main”, you can check [Django’s continuous integration builds](https://djangoci.com) to determine if the failures are specific to your machine or if they are also present in Django’s official builds. If you click to view a particular build, you can view the “Configuration Matrix” which shows failures broken down by Python version and database backend. Note For this tutorial and the ticket we’re working on, testing against SQLite is sufficient, however, it’s possible (and sometimes necessary) to [run the tests using a different database](../../internals/contributing/writing-code/unit-tests/#running-unit-tests-settings). When making UI changes, you will need to [run the Selenium tests](../../internals/contributing/writing-code/unit-tests/#running-selenium-tests). ## Working on an approved new feature[¶](#working-on-an-approved-new-feature "Link to this heading") For this tutorial, we’ll work on a “fake accepted ticket” as a case study. Here are the imaginary details: Ticket #99999 – Allow making toast Django should provide a function `django.shortcuts.make_toast()` that returns `'toast'`. We’ll now implement this feature and associated tests. ## Creating a branch[¶](#creating-a-branch "Link to this heading") Before making any changes, create a new branch for the ticket: /  ``` $ git checkout -b ticket_99999 ``` ** ``` ...\> git checkout -b ticket_99999 ``` ** You can choose any name that you want for the branch, “ticket\_99999” is an example. All changes made in this branch will be specific to the ticket and won’t affect the main copy of the code that we cloned earlier. ## Writing some tests for your ticket[¶](#writing-some-tests-for-your-ticket "Link to this heading") In most cases, for a contribution to be accepted into Django it has to include tests. For bug fix contributions, this means writing a regression test to ensure that the bug is never reintroduced into Django later on. A regression test should be written in such a way that it will fail while the bug still exists and pass once the bug has been fixed. For contributions containing new features, you’ll need to include tests which ensure that the new features are working correctly. They too should fail when the new feature is not present, and then pass once it has been implemented. A good way to do this is to write your new tests first, before making any changes to the code. This style of development is called [test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) and can be applied to both entire projects and single changes. After writing your tests, you then run them to make sure that they do indeed fail (since you haven’t fixed that bug or added that feature yet). If your new tests don’t fail, you’ll need to fix them so that they do. After all, a regression test that passes regardless of whether a bug is present is not very helpful at preventing that bug from reoccurring down the road. Now for our hands-on example. ### Writing a test for ticket #99999[¶](#writing-a-test-for-ticket-99999 "Link to this heading") In order to resolve this ticket, we’ll add a `make_toast()` function to the `django.shortcuts` module. First we are going to write a test that tries to use the function and check that its output looks correct. Navigate to Django’s `tests/shortcuts/` folder and create a new file `test_make_toast.py`. Add the following code: ``` from django.shortcuts import make_toast from django.test import SimpleTestCase class MakeToastTests(SimpleTestCase): def test_make_toast(self): self.assertEqual(make_toast(), "toast") ``` This test checks that the `make_toast()` returns `'toast'`. But this testing thing looks kinda hard… If you’ve never had to deal with tests before, they can look a little hard to write at first glance. Fortunately, testing is a *very* big subject in computer programming, so there’s lots of information out there: * A good first look at writing tests for Django can be found in the documentation on [Writing and running tests](../../topics/testing/overview/). * Dive Into Python (a free online book for beginning Python developers) includes a great [introduction to Unit Testing](https://diveintopython3.net/unit-testing.html). * After reading those, if you want something a little meatier to sink your teeth into, there’s always the Python [`unittest`](https://docs.python.org/3/library/unittest.html#module-unittest "(in Python v3.15)") documentation. ### Running your new test[¶](#running-your-new-test "Link to this heading") Since we haven’t made any modifications to `django.shortcuts` yet, our test should fail. Let’s run all the tests in the `shortcuts` folder to make sure that’s really what happens. `cd` to the Django `tests/` directory and run: /  ``` $ ./runtests.py shortcuts ``` ** ``` ...\> runtests.py shortcuts ``` ** If the tests ran correctly, you should see one failure corresponding to the test method we added, with this error: ``` ImportError: cannot import name 'make_toast' from 'django.shortcuts' ``` If all of the tests passed, then you’ll want to make sure that you added the new test shown above to the appropriate folder and file name. ## Writing the code for your ticket[¶](#writing-the-code-for-your-ticket "Link to this heading") Next we’ll be adding the `make_toast()` function. Navigate to the `django/` folder and open the `shortcuts.py` file. At the bottom, add: ``` def make_toast(): return "toast" ``` Now we need to make sure that the test we wrote earlier passes, so we can see whether the code we added is working correctly. Again, navigate to the Django `tests/` directory and run: /  ``` $ ./runtests.py shortcuts ``` ** ``` ...\> runtests.py shortcuts ``` ** Everything should pass. If it doesn’t, make sure you correctly added the function to the correct file. ## Running Django’s test suite for the second time[¶](#running-django-s-test-suite-for-the-second-time "Link to this heading") Once you’ve verified that your changes and test are working correctly, it’s a good idea to run the entire Django test suite to verify that your change hasn’t introduced any bugs into other areas of Django. While successfully passing the entire test suite doesn’t guarantee your code is bug free, it does help identify many bugs and regressions that might otherwise go unnoticed. To run the entire Django test suite, `cd` into the Django `tests/` directory and run: /  ``` $ ./runtests.py ``` ** ``` ...\> runtests.py ``` ** ## Writing Documentation[¶](#writing-documentation "Link to this heading") This is a new feature, so it should be documented. Open the file `docs/topics/http/shortcuts.txt` and add the following at the end of the file: ``` ``make_toast()`` ================ .. function:: make_toast() .. versionadded:: 6.2 Returns ``'toast'``. ``` Since this new feature will be in an upcoming release it is also added to the release notes for the next version of Django. Open the release notes for the latest version in `docs/releases/`, which at time of writing is `6.2.txt`. Add a note under the “Minor Features” header: ``` :mod:`django.shortcuts` ~~~~~~~~~~~~~~~~~~~~~~~ * The new :func:`django.shortcuts.make_toast` function returns ``'toast'``. ``` For more information on writing documentation, including an explanation of what the `versionadded` bit is all about, see [Writing documentation](../../internals/contributing/writing-documentation/). That page also includes an explanation of how to build a copy of the documentation locally, so you can preview the HTML that will be generated. ## Previewing your changes[¶](#previewing-your-changes "Link to this heading") Now it’s time to review the changes made in the branch. To stage all the changes ready for commit, run: /  ``` $ git add --all ``` ** ``` ...\> git add --all ``` ** Then display the differences between your current copy of Django (with your changes) and the revision that you initially checked out earlier in the tutorial with: /  ``` $ git diff --cached ``` ** ``` ...\> git diff --cached ``` ** Use the arrow keys to move up and down. ``` diff --git a/django/shortcuts.py b/django/shortcuts.py index 7ab1df0e9d..8dde9e28d9 100644 --- a/django/shortcuts.py +++ b/django/shortcuts.py @@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs): # Finally, fall back and assume it's a URL return to + + +def make_toast(): + return 'toast' diff --git a/docs/releases/6.2.txt b/docs/releases/6.2.txt index 7d85d30c4a..81518187b3 100644 --- a/docs/releases/6.2.txt +++ b/docs/releases/6.2.txt @@ -34,6 +34,11 @@ Minor features -------------- +:mod:`django.shortcuts` +~~~~~~~~~~~~~~~~~~~~~~~ + +* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``. + :mod:`django.contrib.admin` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt index 7b3a3a2c00..711bf6bb6d 100644 --- a/docs/topics/http/shortcuts.txt +++ b/docs/topics/http/shortcuts.txt @@ -271,3 +271,12 @@ This example is equivalent to:: my_objects = list(MyModel.objects.filter(published=True)) if not my_objects: raise Http404("No MyModel matches the given query.") + +``make_toast()`` +================ + +.. function:: make_toast() + +.. versionadded:: 6.2 + +Returns ``'toast'``. diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py new file mode 100644 index 0000000000..6f4c627b6e --- /dev/null +++ b/tests/shortcuts/test_make_toast.py @@ -0,0 +1,7 @@ +from django.shortcuts import make_toast +from django.test import SimpleTestCase + + +class MakeToastTests(SimpleTestCase): + def test_make_toast(self): + self.assertEqual(make_toast(), 'toast') ``` When you’re done previewing the changes, hit the `q` key to return to the command line. If the diff looked okay, it’s time to commit the changes. ## Committing the changes[¶](#committing-the-changes "Link to this heading") To commit the changes: /  ``` $ git commit ``` ** ``` ...\> git commit ``` ** This opens up a text editor to type the commit message. Follow the [commit message guidelines](../../internals/contributing/committing-code/#committing-guidelines) and write a message like: ``` Fixed #99999 -- Added a shortcut function to make toast. ``` ## Pushing the commit and making a pull request[¶](#pushing-the-commit-and-making-a-pull-request "Link to this heading") After committing the changes, send it to your fork on GitHub (substitute “ticket\_99999” with the name of your branch if it’s different): /  ``` $ git push origin ticket_99999 ``` ** ``` ...\> git push origin ticket_99999 ``` ** You can create a pull request by visiting the [Django GitHub page](https://github.com/django/django/). You’ll see your branch under “Your recently pushed branches”. Click “Compare & pull request” next to it. Please don’t do it for this tutorial, but on the next page that displays a preview of the changes, you would click “Create pull request”. ## Next steps[¶](#next-steps "Link to this heading") Congratulations, you’ve learned how to make a pull request to Django! Details of more advanced techniques you may need are in [Working with Git and GitHub](../../internals/contributing/writing-code/working-with-git/). Now you can put those skills to good use by helping to improve Django’s codebase. ### More information for new contributors[¶](#more-information-for-new-contributors "Link to this heading") Before you get too into contributing to Django, there’s a little more information on contributing that you should probably take a look at: * You should make sure to read Django’s documentation on [claiming tickets and submitting pull requests](../../internals/contributing/writing-code/submitting-patches/). It covers Trac etiquette, how to claim tickets for yourself, expected coding style (both for code and docs), and many other important details. * First time contributors should also read Django’s [documentation for first time contributors](../../internals/contributing/new-contributors/). It has lots of good advice for those of us who are new to helping out with Django. * After those, if you’re still hungry for more information about contributing, you can always browse through the rest of [Django’s documentation on contributing](../../internals/contributing/). It contains a ton of useful information and should be your first source for answering any questions you might have. ### Finding your first real ticket[¶](#finding-your-first-real-ticket "Link to this heading") Once you’ve looked through some of that information, you’ll be ready to go out and find a ticket of your own to contribute to. Pay special attention to tickets with the “easy pickings” criterion. These tickets are often much simpler in nature and are great for first time contributors. Once you’re familiar with contributing to Django, you can start working on more difficult and complicated tickets. If you just want to get started already (and nobody would blame you!), try taking a look at the list of [easy tickets without a branch](https://code.djangoproject.com/query?status=new\&status=reopened\&has_patch=0\&easy=1\&col=id\&col=summary\&col=status\&col=owner\&col=type\&col=milestone\&order=priority) and the [easy tickets that have branches which need improvement](https://code.djangoproject.com/query?status=new\&status=reopened\&needs_better_patch=1\&easy=1\&col=id\&col=summary\&col=status\&col=owner\&col=type\&col=milestone\&order=priority). If you’re familiar with writing tests, you can also look at the list of [easy tickets that need tests](https://code.djangoproject.com/query?status=new\&status=reopened\&needs_tests=1\&easy=1\&col=id\&col=summary\&col=status\&col=owner\&col=type\&col=milestone\&order=priority). Remember to follow the guidelines about claiming tickets that were mentioned in the link to Django’s documentation on [claiming tickets and submitting branches](../../internals/contributing/writing-code/submitting-patches/). ### What’s next after creating a pull request?[¶](#what-s-next-after-creating-a-pull-request "Link to this heading") After a ticket has a branch, it needs to be reviewed by a second set of eyes. After submitting a pull request, update the ticket metadata by setting the flags on the ticket to say “has patch”, “doesn’t need tests”, etc, so others can find it for review. Contributing doesn’t necessarily always mean writing code from scratch. Reviewing open pull requests is also a very helpful contribution. See [Triaging tickets](../../internals/contributing/triaging-tickets/) for details. [**Back to Top](#top) ## Additional Information ### Support Django! * [CloudBolt Software donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Writing your first contribution for Django](#) * [Introduction](#introduction) * [Who’s this tutorial for?](#who-s-this-tutorial-for) * [What does this tutorial cover?](#what-does-this-tutorial-cover) * [Code of Conduct](#code-of-conduct) * [Installing Git](#installing-git) * [Getting a copy of Django’s development version](#getting-a-copy-of-django-s-development-version) * [Running Django’s test suite for the first time](#running-django-s-test-suite-for-the-first-time) * [Working on an approved new feature](#working-on-an-approved-new-feature) * [Creating a branch](#creating-a-branch) * [Writing some tests for your ticket](#writing-some-tests-for-your-ticket) * [Writing a test for ticket #99999](#writing-a-test-for-ticket-99999) * [Running your new test](#running-your-new-test) * [Writing the code for your ticket](#writing-the-code-for-your-ticket) * [Running Django’s test suite for the second time](#running-django-s-test-suite-for-the-second-time) * [Writing Documentation](#writing-documentation) * [Previewing your changes](#previewing-your-changes) * [Committing the changes](#committing-the-changes) * [Pushing the commit and making a pull request](#pushing-the-commit-and-making-a-pull-request) * [Next steps](#next-steps) * [More information for new contributors](#more-information-for-new-contributors) * [Finding your first real ticket](#finding-your-first-real-ticket) * [What’s next after creating a pull request?](#what-s-next-after-creating-a-pull-request) ---- url: https://docs.djangoproject.com/en/6.1/topics/class-based-views/generic-display/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/class-based-views/generic-display/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/class-based-views/generic-display/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/class-based-views/generic-display/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/class-based-views/generic-display/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/class-based-views/generic-display/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/class-based-views/generic-display/) - [it](https://docs.djangoproject.com/it/6.1/topics/class-based-views/generic-display/) - [id](https://docs.djangoproject.com/id/6.1/topics/class-based-views/generic-display/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/class-based-views/generic-display/) - [es](https://docs.djangoproject.com/es/6.1/topics/class-based-views/generic-display/) - [el](https://docs.djangoproject.com/el/6.1/topics/class-based-views/generic-display/) * * [dev](https://docs.djangoproject.com/en/dev/topics/class-based-views/generic-display/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/class-based-views/generic-display/) * [5.2](https://docs.djangoproject.com/en/5.2/topics/class-based-views/generic-display/) * [5.1](https://docs.djangoproject.com/en/5.1/topics/class-based-views/generic-display/) * [5.0](https://docs.djangoproject.com/en/5.0/topics/class-based-views/generic-display/) * [4.2](https://docs.djangoproject.com/en/4.2/topics/class-based-views/generic-display/) * [4.1](https://docs.djangoproject.com/en/4.1/topics/class-based-views/generic-display/) * [4.0](https://docs.djangoproject.com/en/4.0/topics/class-based-views/generic-display/) * [3.2](https://docs.djangoproject.com/en/3.2/topics/class-based-views/generic-display/) * [3.1](https://docs.djangoproject.com/en/3.1/topics/class-based-views/generic-display/) * [3.0](https://docs.djangoproject.com/en/3.0/topics/class-based-views/generic-display/) * [2.2](https://docs.djangoproject.com/en/2.2/topics/class-based-views/generic-display/) * [2.1](https://docs.djangoproject.com/en/2.1/topics/class-based-views/generic-display/) * [2.0](https://docs.djangoproject.com/en/2.0/topics/class-based-views/generic-display/) * [1.11](https://docs.djangoproject.com/en/1.11/topics/class-based-views/generic-display/) * [1.10](https://docs.djangoproject.com/en/1.10/topics/class-based-views/generic-display/) * [1.9](https://docs.djangoproject.com/en/1.9/topics/class-based-views/generic-display/) * [1.8](https://docs.djangoproject.com/en/1.8/topics/class-based-views/generic-display/) - [**](#top) # Built-in class-based generic views[¶](#built-in-class-based-generic-views "Link to this heading") Writing web applications can be monotonous, because we repeat certain patterns again and again. Django tries to take away some of that monotony at the model and template layers, but web developers also experience this boredom at the view level. Django’s *generic views* were developed to ease that pain. They take certain common idioms and patterns found in view development and abstract them so that you can quickly write common views of data without having to write too much code. We can recognize certain common tasks, like displaying a list of objects, and write code that displays a list of *any* object. Then the model in question can be passed as an extra argument to the URLconf. Django ships with generic views to do the following: * Display list and detail pages for a single object. If we were creating an application to manage conferences then a `TalkListView` and a `RegisteredUserListView` would be examples of list views. A single talk page is an example of what we call a “detail” view. * Present date-based objects in year/month/day archive pages, associated detail, and “latest” pages. * Allow users to create, update, and delete objects – with or without authorization. Taken together, these views provide interfaces to perform the most common tasks developers encounter. ## Extending generic views[¶](#extending-generic-views "Link to this heading") There’s no question that using generic views can speed up development substantially. In most projects, however, there comes a moment when the generic views no longer suffice. Indeed, the most common question asked by new Django developers is how to make generic views handle a wider array of situations. This is one of the reasons generic views were redesigned for the 1.3 release - previously, they were view functions with a bewildering array of options; now, rather than passing in a large amount of configuration in the URLconf, the recommended way to extend generic views is to subclass them, and override their attributes or methods. That said, generic views will have a limit. If you find you’re struggling to implement your view as a subclass of a generic view, then you may find it more effective to write just the code you need, using your own class-based or functional views. More examples of generic views are available in some third party applications, or you could write your own as needed. ## Generic views of objects[¶](#generic-views-of-objects "Link to this heading") [`TemplateView`](../../../ref/class-based-views/base/#django.views.generic.base.TemplateView "django.views.generic.base.TemplateView") certainly is useful, but Django’s generic views really shine when it comes to presenting views of your database content. Because it’s such a common task, Django comes with a handful of built-in generic views to help generate list and detail views of objects. Let’s start by looking at some examples of showing a list of objects or an individual object. We’ll be using these models: ``` # models.py from django.db import models class Publisher(models.Model): name = models.CharField(max_length=30) address = models.CharField(max_length=50) city = models.CharField(max_length=60) state_province = models.CharField(max_length=30) country = models.CharField(max_length=50) website = models.URLField() class Meta: ordering = ["-name"] def __str__(self): return self.name class Author(models.Model): salutation = models.CharField(max_length=10) name = models.CharField(max_length=200) email = models.EmailField() headshot = models.ImageField(upload_to="author_headshots") def __str__(self): return self.name class Book(models.Model): title = models.CharField(max_length=100) authors = models.ManyToManyField("Author") publisher = models.ForeignKey(Publisher, on_delete=models.CASCADE) publication_date = models.DateField() ``` Now we need to define a view: ``` # views.py from django.views.generic import ListView from books.models import Publisher class PublisherListView(ListView): model = Publisher ``` Finally hook that view into your urls: ``` # urls.py from django.urls import path from books.views import PublisherListView urlpatterns = [ path("publishers/", PublisherListView.as_view()), ] ``` That’s all the Python code we need to write. We still need to write a template, however. We could explicitly tell the view which template to use by adding a `template_name` attribute to the view, but in the absence of an explicit template Django will infer one from the object’s name. In this case, the inferred template will be `"books/publisher_list.html"` – the “books” part comes from the name of the app that defines the model, while the “publisher” bit is the lowercased version of the model’s name. Note Thus, when (for example) the `APP_DIRS` option of a `DjangoTemplates` backend is set to True in [`TEMPLATES`](../../../ref/settings/#std-setting-TEMPLATES), a template location could be: /path/to/project/books/templates/books/publisher\_list.html This template will be rendered against a context containing a variable called `object_list` that contains all the publisher objects. A template might look like this: ``` {% extends "base.html" %} {% block content %}

Publishers

    {% for publisher in object_list %}
  • {{ publisher.name }}
    • {% endfor %}
{% endblock %} ``` That’s really all there is to it. All the cool features of generic views come from changing the attributes set on the generic view. The [generic views reference](../../../ref/class-based-views/) documents all the generic views and their options in detail; the rest of this document will consider some of the common ways you might customize and extend generic views. ### Making “friendly” template contexts[¶](#making-friendly-template-contexts "Link to this heading") You might have noticed that our sample publisher list template stores all the publishers in a variable named `object_list`. While this works just fine, it isn’t all that “friendly” to template authors: they have to “just know” that they’re dealing with publishers here. Well, if you’re dealing with a model object, this is already done for you. When you are dealing with an object or queryset, Django is able to populate the context using the lowercased version of the model class’ name. This is provided in addition to the default `object_list` entry, but contains exactly the same data, i.e. `publisher_list`. If this still isn’t a good match, you can manually set the name of the context variable. The `context_object_name` attribute on a generic view specifies the context variable to use: ``` # views.py from django.views.generic import ListView from books.models import Publisher class PublisherListView(ListView): model = Publisher context_object_name = "my_favorite_publishers" ``` Providing a useful `context_object_name` is always a good idea. Your coworkers who design templates will thank you. ### Adding extra context[¶](#adding-extra-context "Link to this heading") Often you need to present some extra information beyond that provided by the generic view. For example, think of showing a list of all the books on each publisher detail page. The [`DetailView`](../../../ref/class-based-views/generic-display/#django.views.generic.detail.DetailView "django.views.generic.detail.DetailView") generic view provides the publisher to the context, but how do we get additional information in that template? The answer is to subclass [`DetailView`](../../../ref/class-based-views/generic-display/#django.views.generic.detail.DetailView "django.views.generic.detail.DetailView") and provide your own implementation of the `get_context_data` method. The default implementation adds the object being displayed to the template, but you can override it to send more: ``` from django.views.generic import DetailView from books.models import Book, Publisher class PublisherDetailView(DetailView): model = Publisher def get_context_data(self, **kwargs): # Call the base implementation first to get a context context = super().get_context_data(**kwargs) # Add in a QuerySet of all the books context["book_list"] = Book.objects.all() return context ``` Note Generally, `get_context_data` will merge the context data of all parent classes with those of the current class. To preserve this behavior in your own classes where you want to alter the context, you should be sure to call `get_context_data` on the super class. When no two classes try to define the same key, this will give the expected results. However if any class attempts to override a key after parent classes have set it (after the call to super), any children of that class will also need to explicitly set it after super if they want to be sure to override all parents. If you’re having trouble, review the method resolution order of your view. Another consideration is that the context data from class-based generic views will override data provided by context processors; see [`get_context_data()`](../../../ref/class-based-views/mixins-single-object/#django.views.generic.detail.SingleObjectMixin.get_context_data "django.views.generic.detail.SingleObjectMixin.get_context_data") for an example. ### Viewing subsets of objects[¶](#viewing-subsets-of-objects "Link to this heading") Now let’s take a closer look at the `model` argument we’ve been using all along. The `model` argument, which specifies the database model that the view will operate upon, is available on all the generic views that operate on a single object or a collection of objects. However, the `model` argument is not the only way to specify the objects that the view will operate upon – you can also specify the list of objects using the `queryset` argument: ``` from django.views.generic import DetailView from books.models import Publisher class PublisherDetailView(DetailView): context_object_name = "publisher" queryset = Publisher.objects.all() ``` Specifying `model = Publisher` is shorthand for saying `queryset = Publisher.objects.all()`. However, by using `queryset` to define a filtered list of objects you can be more specific about the objects that will be visible in the view (see [Making queries](../../db/queries/) for more information about [`QuerySet`](../../../ref/models/querysets/#django.db.models.query.QuerySet "django.db.models.query.QuerySet") objects, and see the [class-based views reference](../../../ref/class-based-views/) for the complete details). To pick an example, we might want to order a list of books by publication date, with the most recent first: ``` from django.views.generic import ListView from books.models import Book class BookListView(ListView): queryset = Book.objects.order_by("-publication_date") context_object_name = "book_list" ``` That’s a pretty minimal example, but it illustrates the idea nicely. You’ll usually want to do more than just reorder objects. If you want to present a list of books by a particular publisher, you can use the same technique: ``` from django.views.generic import ListView from books.models import Book class AcmeBookListView(ListView): context_object_name = "book_list" queryset = Book.objects.filter(publisher__name="ACME Publishing") template_name = "books/acme_list.html" ``` Notice that along with a filtered `queryset`, we’re also using a custom template name. If we didn’t, the generic view would use the same template as the “vanilla” object list, which might not be what we want. Also notice that this isn’t a very elegant way of doing publisher-specific books. If we want to add another publisher page, we’d need another handful of lines in the URLconf, and more than a few publishers would get unreasonable. We’ll deal with this problem in the next section. Note If you get a 404 when requesting `/books/acme/`, check to ensure you actually have a Publisher with the name ‘ACME Publishing’. Generic views have an `allow_empty` parameter for this case. See the [class-based-views reference](../../../ref/class-based-views/) for more details. ### Dynamic filtering[¶](#dynamic-filtering "Link to this heading") Another common need is to filter down the objects given in a list page by some key in the URL. Earlier we hardcoded the publisher’s name in the URLconf, but what if we wanted to write a view that displayed all the books by some arbitrary publisher? Handily, the `ListView` has a [`get_queryset()`](../../../ref/class-based-views/mixins-multiple-object/#django.views.generic.list.MultipleObjectMixin.get_queryset "django.views.generic.list.MultipleObjectMixin.get_queryset") method we can override. By default, it returns the value of the `queryset` attribute, but we can use it to add more logic. The key part to making this work is that when class-based views are called, various useful things are stored on `self`; as well as the request (`self.request`) this includes the positional (`self.args`) and name-based (`self.kwargs`) arguments captured according to the URLconf. Here, we have a URLconf with a single captured group: ``` # urls.py from django.urls import path from books.views import PublisherBookListView urlpatterns = [ path("books//", PublisherBookListView.as_view()), ] ``` Next, we’ll write the `PublisherBookListView` view itself: ``` # views.py from django.shortcuts import get_object_or_404 from django.views.generic import ListView from books.models import Book, Publisher class PublisherBookListView(ListView): template_name = "books/books_by_publisher.html" def get_queryset(self): self.publisher = get_object_or_404(Publisher, name=self.kwargs["publisher"]) return Book.objects.filter(publisher=self.publisher) ``` Using `get_queryset` to add logic to the queryset selection is as convenient as it is powerful. For instance, if we wanted, we could use `self.request.user` to filter using the current user, or other more complex logic. We can also add the publisher into the context at the same time, so we can use it in the template: ``` # ... def get_context_data(self, **kwargs): # Call the base implementation first to get a context context = super().get_context_data(**kwargs) # Add in the publisher context["publisher"] = self.publisher return context ``` ### Performing extra work[¶](#performing-extra-work "Link to this heading") The last common pattern we’ll look at involves doing some extra work before or after calling the generic view. Imagine we had a `last_accessed` field on our `Author` model that we were using to keep track of the last time anybody looked at that author: ``` # models.py from django.db import models class Author(models.Model): salutation = models.CharField(max_length=10) name = models.CharField(max_length=200) email = models.EmailField() headshot = models.ImageField(upload_to="author_headshots") last_accessed = models.DateTimeField() ``` The generic `DetailView` class wouldn’t know anything about this field, but once again we could write a custom view to keep that field updated. First, we’d need to add an author detail bit in the URLconf to point to a custom view: ``` from django.urls import path from books.views import AuthorDetailView urlpatterns = [ # ... path("authors//", AuthorDetailView.as_view(), name="author-detail"), ] ``` Then we’d write our new view – `get_object` is the method that retrieves the object – so we override it and wrap the call: ``` from django.utils import timezone from django.views.generic import DetailView from books.models import Author class AuthorDetailView(DetailView): queryset = Author.objects.all() def get_object(self): obj = super().get_object() # Record the last accessed date obj.last_accessed = timezone.now() obj.save() return obj ``` Note The URLconf here uses the named group `pk` - this name is the default name that `DetailView` uses to find the value of the primary key used to filter the queryset. If you want to call the group something else, you can set [`pk_url_kwarg`](../../../ref/class-based-views/mixins-single-object/#django.views.generic.detail.SingleObjectMixin.pk_url_kwarg "django.views.generic.detail.SingleObjectMixin.pk_url_kwarg") on the view. [**Back to Top](#top) ## Additional Information ### Support Django! * [Nuhil Mehdy donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Built-in class-based generic views](#) * [Extending generic views](#extending-generic-views) * [Generic views of objects](#generic-views-of-objects) * [Making “friendly” template contexts](#making-friendly-template-contexts) * [Adding extra context](#adding-extra-context) * [Viewing subsets of objects](#viewing-subsets-of-objects) * [Dynamic filtering](#dynamic-filtering) * [Performing extra work](#performing-extra-work) ---- url: https://docs.djangoproject.com/en/6.1/ref/class-based-views/mixins/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/class-based-views/mixins/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/class-based-views/mixins/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/class-based-views/mixins/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/class-based-views/mixins/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/class-based-views/mixins/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/class-based-views/mixins/) - [it](https://docs.djangoproject.com/it/6.1/ref/class-based-views/mixins/) - [id](https://docs.djangoproject.com/id/6.1/ref/class-based-views/mixins/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/class-based-views/mixins/) - [es](https://docs.djangoproject.com/es/6.1/ref/class-based-views/mixins/) - [el](https://docs.djangoproject.com/el/6.1/ref/class-based-views/mixins/) * * [dev](https://docs.djangoproject.com/en/dev/ref/class-based-views/mixins/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/class-based-views/mixins/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/class-based-views/mixins/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/class-based-views/mixins/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/class-based-views/mixins/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/class-based-views/mixins/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/class-based-views/mixins/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/class-based-views/mixins/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/class-based-views/mixins/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/class-based-views/mixins/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/class-based-views/mixins/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/class-based-views/mixins/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/class-based-views/mixins/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/class-based-views/mixins/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/class-based-views/mixins/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/class-based-views/mixins/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/class-based-views/mixins/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/class-based-views/mixins/) - [**](#top) # Class-based views mixins[¶](#class-based-views-mixins "Link to this heading") Class-based views API reference. For introductory material, see [Using mixins with class-based views](../../../topics/class-based-views/mixins/). * [Simple mixins](../mixins-simple/) * [Single object mixins](../mixins-single-object/) * [Multiple object mixins](../mixins-multiple-object/) * [Editing mixins](../mixins-editing/) * [Date-based mixins](../mixins-date-based/) [**Back to Top](#top) ## Additional Information ### Support Django! * [KimSia, Sim donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Class-based views mixins](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.1.3/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.1.3/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.1.3/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.1.3/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.1.3/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.1.3/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.1.3/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.1.3/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.1.3/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.1.3/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.1.3/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.1.3/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.1.3/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.1.3/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.1.3/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.1.3/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.1.3/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.1.3/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.1.3/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.1.3/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.1.3/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.1.3/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.1.3/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.1.3/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.1.3/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.1.3/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.1.3/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.1.3/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.1.3/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.1.3/) - [**](#top) # Django 1.1.3 release notes[¶](#django-1-1-3-release-notes "Link to this heading") Welcome to Django 1.1.3! This is the third “bugfix” release in the Django 1.1 series, improving the stability and performance of the Django 1.1 codebase. With one exception, Django 1.1.3 maintains backwards compatibility with Django 1.1.2. It also contains a number of fixes and other improvements. Django 1.1.2 is a recommended upgrade for any development or deployment currently using or targeting Django 1.1. For full details on the new features, backwards incompatibilities, and deprecated features in the 1.1 branch, see the [Django 1.1 release notes](../1.1/). ## Backwards incompatible changes[¶](#backwards-incompatible-changes "Link to this heading") ### Restricted filters in admin interface[¶](#restricted-filters-in-admin-interface "Link to this heading") The Django administrative interface, `django.contrib.admin`, supports filtering of displayed lists of objects by fields on the corresponding models, including across database-level relationships. This is implemented by passing lookup arguments in the querystring portion of the URL, and options on the ModelAdmin class allow developers to specify particular fields or relationships which will generate automatic links for filtering. One historically-undocumented and -unofficially-supported feature has been the ability for a user with sufficient knowledge of a model’s structure and the format of these lookup arguments to invent useful new filters on the fly by manipulating the querystring. However, it has been demonstrated that this can be abused to gain access to information outside of an admin user’s permissions; for example, an attacker with access to the admin and sufficient knowledge of model structure and relations could construct query strings which – with repeated use of regular-expression lookups supported by the Django database API – expose sensitive information such as users’ password hashes. To remedy this, `django.contrib.admin` will now validate that querystring lookup arguments either specify only fields on the model being viewed, or cross relations which have been explicitly allowed by the application developer using the preexisting mechanism mentioned above. This is backwards-incompatible for any users relying on the prior ability to insert arbitrary lookups. [**Back to Top](#top) ## Additional Information ### Support Django! * [Eau Claire Tree Service donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.1.3 release notes](#) * [Backwards incompatible changes](#backwards-incompatible-changes) * [Restricted filters in admin interface](#restricted-filters-in-admin-interface) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.6.11/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.6.11/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.6.11/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.6.11/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.6.11/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.6.11/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.6.11/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.6.11/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.6.11/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.6.11/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.6.11/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.6.11/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.6.11/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.6.11/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.6.11/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.6.11/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.6.11/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.6.11/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.6.11/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.6.11/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.6.11/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.6.11/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.6.11/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.6.11/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.6.11/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.6.11/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.6.11/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.6.11/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.6.11/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.6.11/) - [**](#top) # Django 1.6.11 release notes[¶](#django-1-6-11-release-notes "Link to this heading") *March 18, 2015* Django 1.6.11 fixes two security issues in 1.6.10. ## Denial-of-service possibility with `strip_tags()`[¶](#denial-of-service-possibility-with-strip-tags "Link to this heading") Last year [`strip_tags()`](../../ref/utils/#django.utils.html.strip_tags "django.utils.html.strip_tags") was changed to work iteratively. The problem is that the size of the input it’s processing can increase on each iteration which results in an infinite loop in `strip_tags()`. This issue only affects versions of Python that haven’t received [a bugfix in HTMLParser](https://bugs.python.org/issue?@action=redirect\&bpo=20288); namely Python < 2.7.7 and 3.3.5. Some operating system vendors have also backported the fix for the Python bug into their packages of earlier versions. To remedy this issue, `strip_tags()` will now return the original input if it detects the length of the string it’s processing increases. Remember that absolutely NO guarantee is provided about the results of `strip_tags()` being HTML safe. So NEVER mark safe the result of a `strip_tags()` call without escaping it first, for example with [`escape()`](../../ref/utils/#django.utils.html.escape "django.utils.html.escape"). ## Mitigated possible XSS attack via user-supplied redirect URLs[¶](#mitigated-possible-xss-attack-via-user-supplied-redirect-urls "Link to this heading") Django relies on user input in some cases (e.g. `django.contrib.auth.views.login()` and [i18n](../../topics/i18n/)) to redirect the user to an “on success” URL. The security checks for these redirects (namely `django.utils.http.is_safe_url()`) accepted URLs with leading control characters and so considered URLs like `\x08javascript:...` safe. This issue doesn’t affect Django currently, since we only put this URL into the `Location` response header and browsers seem to ignore JavaScript there. Browsers we tested also treat URLs prefixed with control characters such as `%08//example.com` as relative paths so redirection to an unsafe target isn’t a problem either. However, if a developer relies on `is_safe_url()` to provide safe redirect targets and puts such a URL into a link, they could suffer from an XSS attack as some browsers such as Google Chrome ignore control characters at the start of a URL in an anchor `href`. [**Back to Top](#top) ## Additional Information ### Support Django! * [Michael van Tellingen donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.6.11 release notes](#) * [Denial-of-service possibility with `strip_tags()`](#denial-of-service-possibility-with-strip-tags) ---- url: https://docs.djangoproject.com/en/6.1/releases/2.0.10/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/2.0.10/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/2.0.10/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/2.0.10/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/2.0.10/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/2.0.10/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/2.0.10/) - [it](https://docs.djangoproject.com/it/6.1/releases/2.0.10/) - [id](https://docs.djangoproject.com/id/6.1/releases/2.0.10/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/2.0.10/) - [es](https://docs.djangoproject.com/es/6.1/releases/2.0.10/) - [el](https://docs.djangoproject.com/el/6.1/releases/2.0.10/) * * [dev](https://docs.djangoproject.com/en/dev/releases/2.0.10/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/2.0.10/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/2.0.10/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/2.0.10/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/2.0.10/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/2.0.10/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/2.0.10/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/2.0.10/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/2.0.10/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/2.0.10/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/2.0.10/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/2.0.10/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/2.0.10/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/2.0.10/) - [**](#top) # Django 2.0.10 release notes[¶](#django-2-0-10-release-notes "Link to this heading") *January 4, 2019* Django 2.0.10 fixes a security issue and several bugs in 2.0.9. ## CVE-2019-3498: Content spoofing possibility in the default 404 page[¶](#cve-2019-3498-content-spoofing-possibility-in-the-default-404-page "Link to this heading") An attacker could craft a malicious URL that could make spoofed content appear on the default page generated by the `django.views.defaults.page_not_found()` view. The URL path is no longer displayed in the default 404 template and the `request_path` context variable is now quoted to fix the issue for custom templates that use the path. ### Bugfixes[¶](#bugfixes "Link to this heading") * Prevented repetitive calls to `geos_version_tuple()` in the `WKBWriter` class in an attempt to fix a random crash involving `LooseVersion` since Django 2.0.6 ([#29959](https://code.djangoproject.com/ticket/29959)). * Fixed a schema corruption issue on SQLite 3.26+. You might have to drop and rebuild your SQLite database if you applied a migration while using an older version of Django with SQLite 3.26 or later ([#29182](https://code.djangoproject.com/ticket/29182)). * Prevented SQLite schema alterations while foreign key checks are enabled to avoid the possibility of schema corruption ([#30023](https://code.djangoproject.com/ticket/30023)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Philipp Bosch donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 2.0.10 release notes](#) * [CVE-2019-3498: Content spoofing possibility in the default 404 page](#cve-2019-3498-content-spoofing-possibility-in-the-default-404-page) * [Bugfixes](#bugfixes) ---- url: https://docs.djangoproject.com/en/6.1/releases/4.0.9/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/4.0.9/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/4.0.9/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/4.0.9/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/4.0.9/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/4.0.9/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/4.0.9/) - [it](https://docs.djangoproject.com/it/6.1/releases/4.0.9/) - [id](https://docs.djangoproject.com/id/6.1/releases/4.0.9/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/4.0.9/) - [es](https://docs.djangoproject.com/es/6.1/releases/4.0.9/) - [el](https://docs.djangoproject.com/el/6.1/releases/4.0.9/) * * [dev](https://docs.djangoproject.com/en/dev/releases/4.0.9/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/4.0.9/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/4.0.9/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/4.0.9/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/4.0.9/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/4.0.9/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/4.0.9/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/4.0.9/) - [**](#top) # Django 4.0.9 release notes[¶](#django-4-0-9-release-notes "Link to this heading") *February 1, 2023* Django 4.0.9 fixes a security issue with severity “moderate” in 4.0.8. ## CVE-2023-23969: Potential denial-of-service via `Accept-Language` headers[¶](#cve-2023-23969-potential-denial-of-service-via-accept-language-headers "Link to this heading") The parsed values of `Accept-Language` headers are cached in order to avoid repetitive parsing. This leads to a potential denial-of-service vector via excessive memory usage if large header values are sent. In order to avoid this vulnerability, the `Accept-Language` header is now parsed up to a maximum length. [**Back to Top](#top) ## Additional Information ### Support Django! * [Andrés Pérez-Albela H. donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 4.0.9 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/5.2.2/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/5.2.2/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/5.2.2/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/5.2.2/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/5.2.2/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/5.2.2/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/5.2.2/) - [it](https://docs.djangoproject.com/it/6.1/releases/5.2.2/) - [id](https://docs.djangoproject.com/id/6.1/releases/5.2.2/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/5.2.2/) - [es](https://docs.djangoproject.com/es/6.1/releases/5.2.2/) - [el](https://docs.djangoproject.com/el/6.1/releases/5.2.2/) * * [dev](https://docs.djangoproject.com/en/dev/releases/5.2.2/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/5.2.2/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/5.2.2/) - [**](#top) # Django 5.2.2 release notes[¶](#django-5-2-2-release-notes "Link to this heading") *June 4, 2025* Django 5.2.2 fixes a security issue with severity “low” and several bugs in 5.2.1. ## CVE-2025-48432: Potential log injection via unescaped request path[¶](#cve-2025-48432-potential-log-injection-via-unescaped-request-path "Link to this heading") Internal HTTP response logging used `request.path` directly, allowing control characters (e.g. newlines or ANSI escape sequences) to be written unescaped into logs. This could enable log injection or forgery, letting attackers manipulate log appearance or structure, especially in logs processed by external systems or viewed in terminals. Although this does not directly impact Django’s security model, it poses risks when logs are consumed or interpreted by other tools. To fix this, the internal `django.utils.log.log_response()` function now escapes all positional formatting arguments using a safe encoding. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a crash when using `select_related` against a `ForeignObject` originating from a model with a `CompositePrimaryKey` ([#36373](https://code.djangoproject.com/ticket/36373)). * Fixed a bug in Django 5.2 where subqueries using `"pk"` to reference models with a `CompositePrimaryKey` failed to raise `ValueError` when too many or too few columns were selected ([#36392](https://code.djangoproject.com/ticket/36392)). * Fixed a regression in Django 5.2 that caused a crash when no arguments were passed into `QuerySet.union()` ([#36388](https://code.djangoproject.com/ticket/36388)). * Fixed a regression in Django 5.2 where subclasses of `RemoteUserMiddleware` that had overridden `process_request()` were no longer supported ([#36390](https://code.djangoproject.com/ticket/36390)). * Fixed a regression in Django 5.2 that caused a crash when using `OuterRef` in the `filter` argument of an `Aggregate` expression ([#36404](https://code.djangoproject.com/ticket/36404)). * Fixed a regression in Django 5.2 that caused a crash when using `OuterRef` in PostgreSQL aggregate functions `ArrayAgg`, `StringAgg`, and `JSONBAgg` ([#36405](https://code.djangoproject.com/ticket/36405)). * Fixed a regression in Django 5.2 where admin’s `filter_horizontal` buttons lacked `type="button"`, causing them to intercept form submission when pressing the Enter key ([#36423](https://code.djangoproject.com/ticket/36423)). * Fixed a bug in Django 5.2 where calling `QuerySet.in_bulk()` with an `id_list` argument on models with a `CompositePrimaryKey` failed to observe database parameter limits ([#36416](https://code.djangoproject.com/ticket/36416)). * Fixed a bug in Django 5.2 where [`HttpRequest.get_preferred_type()`](../../ref/request-response/#django.http.HttpRequest.get_preferred_type "django.http.HttpRequest.get_preferred_type") did not account for media type parameters in `Accept` headers, reducing specificity in content negotiation ([#36411](https://code.djangoproject.com/ticket/36411)). * Fixed a regression in Django 5.2 that caused a crash when using `QuerySet.prefetch_related()` to prefetch a foreign key with a `Prefetch` queryset for a subclass of the foreign target ([#36432](https://code.djangoproject.com/ticket/36432)). [**Back to Top](#top) ## Additional Information ### Support Django! * [PlantDemand donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 5.2.2 release notes](#) * [CVE-2025-48432: Potential log injection via unescaped request path](#cve-2025-48432-potential-log-injection-via-unescaped-request-path) ---- url: https://docs.djangoproject.com/en/6.1/howto/upgrade-version/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/howto/upgrade-version/) - [sv](https://docs.djangoproject.com/sv/6.1/howto/upgrade-version/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/howto/upgrade-version/) - [pl](https://docs.djangoproject.com/pl/6.1/howto/upgrade-version/) - [ko](https://docs.djangoproject.com/ko/6.1/howto/upgrade-version/) - [ja](https://docs.djangoproject.com/ja/6.1/howto/upgrade-version/) - [it](https://docs.djangoproject.com/it/6.1/howto/upgrade-version/) - [id](https://docs.djangoproject.com/id/6.1/howto/upgrade-version/) - [fr](https://docs.djangoproject.com/fr/6.1/howto/upgrade-version/) - [es](https://docs.djangoproject.com/es/6.1/howto/upgrade-version/) - [el](https://docs.djangoproject.com/el/6.1/howto/upgrade-version/) * * [dev](https://docs.djangoproject.com/en/dev/howto/upgrade-version/) * [6.0](https://docs.djangoproject.com/en/6.0/howto/upgrade-version/) * [5.2](https://docs.djangoproject.com/en/5.2/howto/upgrade-version/) * [5.1](https://docs.djangoproject.com/en/5.1/howto/upgrade-version/) * [5.0](https://docs.djangoproject.com/en/5.0/howto/upgrade-version/) * [4.2](https://docs.djangoproject.com/en/4.2/howto/upgrade-version/) * [4.1](https://docs.djangoproject.com/en/4.1/howto/upgrade-version/) * [4.0](https://docs.djangoproject.com/en/4.0/howto/upgrade-version/) * [3.2](https://docs.djangoproject.com/en/3.2/howto/upgrade-version/) * [3.1](https://docs.djangoproject.com/en/3.1/howto/upgrade-version/) * [3.0](https://docs.djangoproject.com/en/3.0/howto/upgrade-version/) * [2.2](https://docs.djangoproject.com/en/2.2/howto/upgrade-version/) * [2.1](https://docs.djangoproject.com/en/2.1/howto/upgrade-version/) * [2.0](https://docs.djangoproject.com/en/2.0/howto/upgrade-version/) * [1.11](https://docs.djangoproject.com/en/1.11/howto/upgrade-version/) * [1.10](https://docs.djangoproject.com/en/1.10/howto/upgrade-version/) * [1.9](https://docs.djangoproject.com/en/1.9/howto/upgrade-version/) * [1.8](https://docs.djangoproject.com/en/1.8/howto/upgrade-version/) - [**](#top) # How to upgrade Django to a newer version[¶](#how-to-upgrade-django-to-a-newer-version "Link to this heading") Upgrading Django to the latest version offers several benefits: * New features and improvements become available. * Bugs are fixed. * Older versions of Django eventually stop receiving security updates (see [Supported versions](../../internals/release-process/#supported-versions-policy)). * Upgrading with each new release helps keep your code base current and makes future upgrades smoother. Tools to help with version upgrades Django has a vibrant ecosystem. There are automated upgrade helpers highlighted on the [Community Ecosystem](https://www.djangoproject.com/community/ecosystem/#upgrade-utilities) page. Here are some things to consider to help make your upgrade process as smooth as possible. ## Required Reading[¶](#required-reading "Link to this heading") If it’s your first time doing an upgrade, it is useful to read the [guide on the different release processes](../../internals/release-process/). Afterward, you should familiarize yourself with the changes that were made in the new Django version(s): * Read the [release notes](../../releases/) for each ‘final’ release from the one after your current Django version, up to and including the version to which you plan to upgrade. * Look at the [deprecation timeline](../../internals/deprecation/) for the relevant versions. Pay particular attention to backwards incompatible changes to get a clear idea of what will be needed for a successful upgrade. If you’re upgrading through more than one feature version (e.g. 2.0 to 2.2), it’s usually easier to upgrade through each feature release incrementally (2.0 to 2.1 to 2.2) rather than to make all the changes for each feature release at once. For each feature release, use the latest patch release (e.g. for 2.1, use 2.1.15). The same incremental upgrade approach is recommended when upgrading from one LTS to the next. ## Dependencies[¶](#dependencies "Link to this heading") In most cases it will be necessary to upgrade to the latest version of your Django-related dependencies as well. If the Django version was recently released or if some of your dependencies are not well-maintained, some of your dependencies may not yet support the new Django version. In these cases you may have to wait until new versions of your dependencies are released. ## Resolving deprecation warnings[¶](#resolving-deprecation-warnings "Link to this heading") Before upgrading, it’s a good idea to resolve any deprecation warnings raised by your project while using your current version of Django. Fixing these warnings before upgrading ensures that you’re informed about areas of the code that need altering. In Python, deprecation warnings are silenced by default. You must turn them on using the `-Wa` Python command line option or the [`PYTHONWARNINGS`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONWARNINGS "(in Python v3.15)") environment variable. For example, to show warnings while running tests: /  ``` $ python -Wa manage.py test ``` ** ``` ...\> py -Wa manage.py test ``` ** If you’re not using the Django test runner, you may need to also ensure that any console output is not captured which would hide deprecation warnings. For example, if you use [pytest](https://docs.pytest.org/): ``` $ PYTHONWARNINGS=always pytest tests --capture=no ``` Resolve any deprecation warnings with your current version of Django before continuing the upgrade process. Third party applications might use deprecated APIs in order to support multiple versions of Django, so deprecation warnings in packages you’ve installed don’t necessarily indicate a problem. If a package doesn’t support the latest version of Django, consider raising an issue or sending a pull request for it. ## Installation[¶](#installation "Link to this heading") Once you’re ready, it is time to [install the new Django version](../../topics/install/). If you are using a [`virtual environment`](https://docs.python.org/3/library/venv.html#module-venv "(in Python v3.15)") and it is a major upgrade, you might want to set up a new environment with all the dependencies first. If you installed Django with [pip](https://pip.pypa.io/), you can use the `--upgrade` or `-U` flag: /  ``` $ python -m pip install -U Django ``` ** ``` ...\> py -m pip install -U Django ``` ** ## Testing[¶](#testing "Link to this heading") When the new environment is set up, [run the full test suite](../../topics/testing/overview/) for your application. Again, it’s useful to turn on deprecation warnings on so they’re shown in the test output (you can also use the flag if you test your app manually using `manage.py runserver`): /  ``` $ python -Wa manage.py test ``` ** ``` ...\> py -Wa manage.py test ``` ** After you have run the tests, fix any failures. While you have the release notes fresh in your mind, it may also be a good time to take advantage of new features in Django by refactoring your code to eliminate any deprecation warnings. If you are upgrading to an alpha, beta, or release candidate, please see our guide on [How to test pre-release versions of Django](../../internals/contributing/bugs-and-features/#testing-pre-releases) for more specific tips about catching regressions and reporting bugs. ## Deployment[¶](#deployment "Link to this heading") When you are sufficiently confident your app works with the new version of Django, you’re ready to go ahead and [deploy](../deployment/) your upgraded Django project. If you are using caching provided by Django, you should consider clearing your cache after upgrading. Otherwise you may run into problems, for example, if you are caching pickled objects as these objects are not guaranteed to be pickle-compatible across Django versions. A past instance of incompatibility was caching pickled [`HttpResponse`](../../ref/request-response/#django.http.HttpResponse "django.http.HttpResponse") objects, either directly or indirectly via the [`cache_page()`](../../topics/cache/#django.views.decorators.cache.cache_page "django.views.decorators.cache.cache_page") decorator. [**Back to Top](#top) ## Additional Information ### Support Django! * [SaaS Pegasus donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [How to upgrade Django to a newer version](#) * [Required Reading](#required-reading) * [Dependencies](#dependencies) * [Resolving deprecation warnings](#resolving-deprecation-warnings) * [Installation](#installation) * [Testing](#testing) * [Deployment](#deployment) ---- url: https://docs.djangoproject.com/en/6.1/ref/paginator/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/paginator/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/paginator/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/paginator/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/paginator/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/paginator/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/paginator/) - [it](https://docs.djangoproject.com/it/6.1/ref/paginator/) - [id](https://docs.djangoproject.com/id/6.1/ref/paginator/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/paginator/) - [es](https://docs.djangoproject.com/es/6.1/ref/paginator/) - [el](https://docs.djangoproject.com/el/6.1/ref/paginator/) * * [dev](https://docs.djangoproject.com/en/dev/ref/paginator/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/paginator/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/paginator/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/paginator/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/paginator/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/paginator/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/paginator/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/paginator/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/paginator/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/paginator/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/paginator/) - [**](#top) # Paginator[¶](#paginator "Link to this heading") Django provides a few classes that help you manage paginated data – that is, data that’s split across several pages, with “Previous/Next” links. These classes live in [django/core/paginator.py](https://github.com/django/django/blob/main/django/core/paginator.py). For examples, see the [Pagination topic guide](../../topics/pagination/). ## `Paginator` class[¶](#paginator-class "Link to this heading") * *class *Paginator(*object\_list*, *per\_page*, *orphans=0*, *allow\_empty\_first\_page=True*, *error\_messages=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L147)[¶](#django.core.paginator.Paginator "Link to this definition") A paginator acts like a sequence of [`Page`](#django.core.paginator.Page "django.core.paginator.Page") when using `len()` or iterating it directly. - Paginator.object\_list[¶](#django.core.paginator.Paginator.object_list "Link to this definition") Required. A list, tuple, `QuerySet`, or other sliceable object with a `count()` or `__len__()` method. For consistent pagination, `QuerySet`s should be ordered, e.g. with an [`order_by()`](../models/querysets/#django.db.models.query.QuerySet.order_by "django.db.models.query.QuerySet.order_by") clause or with a default [`ordering`](../models/options/#django.db.models.Options.ordering "django.db.models.Options.ordering") on the model. Performance issues paginating large `QuerySet`s If you’re using a `QuerySet` with a very large number of items, requesting high page numbers might be slow on some databases, because the resulting `LIMIT`/`OFFSET` query needs to count the number of `OFFSET` records which takes longer as the page number gets higher. * Paginator.per\_page[¶](#django.core.paginator.Paginator.per_page "Link to this definition") Required. The maximum number of items to include on a page, not including orphans (see the [`orphans`](#django.core.paginator.Paginator.orphans "django.core.paginator.Paginator.orphans") optional argument below). - Paginator.orphans[¶](#django.core.paginator.Paginator.orphans "Link to this definition") Optional. Use this when you don’t want to have a last page with very few items. If the last page would normally have a number of items less than or equal to `orphans`, then those items will be added to the previous page (which becomes the last page) instead of leaving the items on a page by themselves. For example, with 23 items, `per_page=10`, and `orphans=3`, there will be two pages; the first page with 10 items and the second (and last) page with 13 items. `orphans` defaults to zero, which means pages are never combined and the last page may have one item. `orphans` should be less than the [`per_page`](#django.core.paginator.Paginator.per_page "django.core.paginator.Paginator.per_page") value. Deprecated since version 6.0: Support for the `orphans` argument being larger than or equal to the `per_page` argument is deprecated. * Paginator.allow\_empty\_first\_page[¶](#django.core.paginator.Paginator.allow_empty_first_page "Link to this definition") Optional. Whether or not the first page is allowed to be empty. If `False` and `object_list` is empty, then an `EmptyPage` error will be raised. - Paginator.error\_messages[¶](#django.core.paginator.Paginator.error_messages "Link to this definition") The `error_messages` argument lets you override the default messages that the paginator will raise. Pass in a dictionary with keys matching the error messages you want to override. Available error message keys are: `invalid_page`, `min_page`, and `no_results`. For example, here is the default error message: ``` >>> from django.core.paginator import Paginator >>> paginator = Paginator([1, 2, 3], 2) >>> paginator.page(5) Traceback (most recent call last): ... EmptyPage: That page contains no results ``` And here is a custom error message: ``` >>> paginator = Paginator( ... [1, 2, 3], ... 2, ... error_messages={"no_results": "Page does not exist"}, ... ) >>> paginator.page(5) Traceback (most recent call last): ... EmptyPage: Page does not exist ``` ### Methods[¶](#methods "Link to this heading") * Paginator.get\_page(*number*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L155)[¶](#django.core.paginator.Paginator.get_page "Link to this definition") Returns a [`Page`](#django.core.paginator.Page "django.core.paginator.Page") object with the given 1-based index, while also handling out of range and invalid page numbers. If the page isn’t a number, it returns the first page. If the page number is negative or greater than the number of pages, it returns the last page. Raises an [`EmptyPage`](#django.core.paginator.EmptyPage "django.core.paginator.EmptyPage") exception only if you specify `Paginator(..., allow_empty_first_page=False)` and the `object_list` is empty. - Paginator.page(*number*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L168)[¶](#django.core.paginator.Paginator.page "Link to this definition") Returns a [`Page`](#django.core.paginator.Page "django.core.paginator.Page") object with the given 1-based index. Raises [`PageNotAnInteger`](#django.core.paginator.PageNotAnInteger "django.core.paginator.PageNotAnInteger") if the `number` cannot be converted to an integer by calling `int()`. Raises [`EmptyPage`](#django.core.paginator.EmptyPage "django.core.paginator.EmptyPage") if the given page number doesn’t exist. * Paginator.get\_elided\_page\_range(*number*, *\**, *on\_each\_side=3*, *on\_ends=2*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L201)[¶](#django.core.paginator.Paginator.get_elided_page_range "Link to this definition") Returns a 1-based list of page numbers similar to [`Paginator.page_range`](#django.core.paginator.Paginator.page_range "django.core.paginator.Paginator.page_range"), but may add an ellipsis to either or both sides of the current page number when [`Paginator.num_pages`](#django.core.paginator.Paginator.num_pages "django.core.paginator.Paginator.num_pages") is large. The number of pages to include on each side of the current page number is determined by the `on_each_side` argument which defaults to 3. The number of pages to include at the beginning and end of page range is determined by the `on_ends` argument which defaults to 2. For example, with the default values for `on_each_side` and `on_ends`, if the current page is 10 and there are 50 pages, the page range will be `[1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]`. This will result in pages 7, 8, and 9 to the left of and 11, 12, and 13 to the right of the current page as well as pages 1 and 2 at the start and 49 and 50 at the end. Raises [`InvalidPage`](#django.core.paginator.InvalidPage "django.core.paginator.InvalidPage") if the given page number doesn’t exist. ### Attributes[¶](#attributes "Link to this heading") * Paginator.ELLIPSIS[¶](#django.core.paginator.Paginator.ELLIPSIS "Link to this definition") A translatable string used as a substitute for elided page numbers in the page range returned by [`get_elided_page_range()`](#django.core.paginator.Paginator.get_elided_page_range "django.core.paginator.Paginator.get_elided_page_range"). Default is `'…'`. - Paginator.count[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L178)[¶](#django.core.paginator.Paginator.count "Link to this definition") The total number of objects, across all pages. Note When determining the number of objects contained in `object_list`, `Paginator` will first try calling `object_list.count()`. If `object_list` has no `count()` method, then `Paginator` will fall back to using `len(object_list)`. This allows objects, such as `QuerySet`, to use a more efficient `count()` method when available. * Paginator.num\_pages[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L186)[¶](#django.core.paginator.Paginator.num_pages "Link to this definition") The total number of pages. - Paginator.page\_range[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L194)[¶](#django.core.paginator.Paginator.page_range "Link to this definition") A 1-based range iterator of page numbers, e.g. yielding `[1, 2, 3, 4]`. ## `AsyncPaginator` class[¶](#asyncpaginator-class "Link to this heading") New in Django 6.0. * *class *AsyncPaginator(*object\_list*, *per\_page*, *orphans=0*, *allow\_empty\_first\_page=True*, *error\_messages=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L208)[¶](#django.core.paginator.AsyncPaginator "Link to this definition") Asynchronous version of [`Paginator`](#django.core.paginator.Paginator "django.core.paginator.Paginator"). `AsyncPaginator` has the same attributes and signatures as [`Paginator`](#django.core.paginator.Paginator "django.core.paginator.Paginator"), with the following exceptions: * The attribute [`Paginator.count`](#django.core.paginator.Paginator.count "django.core.paginator.Paginator.count") is supported as an asynchronous method `AsyncPaginator.acount()`. * The attribute [`Paginator.num_pages`](#django.core.paginator.Paginator.num_pages "django.core.paginator.Paginator.num_pages") is supported as an asynchronous method `AsyncPaginator.anum_pages()`. * The attribute [`Paginator.page_range`](#django.core.paginator.Paginator.page_range "django.core.paginator.Paginator.page_range") is supported as an asynchronous method `AsyncPaginator.apage_range()`. `AsyncPaginator` has asynchronous versions of the same methods as [`Paginator`](#django.core.paginator.Paginator "django.core.paginator.Paginator"), using an `a` prefix - for example, use `await async_paginator.aget_page(number)` rather than `paginator.get_page(number)`. ## `Page` class[¶](#page-class "Link to this heading") You usually won’t construct `Page` objects by hand – you’ll get them by iterating [`Paginator`](#django.core.paginator.Paginator "django.core.paginator.Paginator"), or by using [`Paginator.page()`](#django.core.paginator.Paginator.page "django.core.paginator.Paginator.page"). * *class *Page(*object\_list*, *number*, *paginator*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L302)[¶](#django.core.paginator.Page "Link to this definition") A page acts like a sequence of [`Page.object_list`](#django.core.paginator.Page.object_list "django.core.paginator.Page.object_list") when using `len()` or iterating it directly. ### Methods[¶](#id1 "Link to this heading") * Page.has\_next()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L326)[¶](#django.core.paginator.Page.has_next "Link to this definition") Returns `True` if there’s a next page. - Page.has\_previous()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L329)[¶](#django.core.paginator.Page.has_previous "Link to this definition") Returns `True` if there’s a previous page. * Page.has\_other\_pages()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L332)[¶](#django.core.paginator.Page.has_other_pages "Link to this definition") Returns `True` if there’s a next **or** previous page. - Page.next\_page\_number()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L335)[¶](#django.core.paginator.Page.next_page_number "Link to this definition") Returns the next page number. Raises [`InvalidPage`](#django.core.paginator.InvalidPage "django.core.paginator.InvalidPage") if next page doesn’t exist. * Page.previous\_page\_number()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L338)[¶](#django.core.paginator.Page.previous_page_number "Link to this definition") Returns the previous page number. Raises [`InvalidPage`](#django.core.paginator.InvalidPage "django.core.paginator.InvalidPage") if previous page doesn’t exist. - Page.start\_index()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L341)[¶](#django.core.paginator.Page.start_index "Link to this definition") Returns the 1-based index of the first object on the page, relative to all of the objects in the paginator’s list. For example, when paginating a list of 5 objects with 2 objects per page, the second page’s [`start_index()`](#django.core.paginator.Page.start_index "django.core.paginator.Page.start_index") would return `3`. * Page.end\_index()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L351)[¶](#django.core.paginator.Page.end_index "Link to this definition") Returns the 1-based index of the last object on the page, relative to all of the objects in the paginator’s list. For example, when paginating a list of 5 objects with 2 objects per page, the second page’s [`end_index()`](#django.core.paginator.Page.end_index "django.core.paginator.Page.end_index") would return `4`. ### Attributes[¶](#id2 "Link to this heading") * Page.object\_list[¶](#django.core.paginator.Page.object_list "Link to this definition") The list of objects on this page. - Page.number[¶](#django.core.paginator.Page.number "Link to this definition") The 1-based page number for this page. * Page.paginator[¶](#django.core.paginator.Page.paginator "Link to this definition") The associated [`Paginator`](#django.core.paginator.Paginator "django.core.paginator.Paginator") object. ## `AsyncPage` class[¶](#asyncpage-class "Link to this heading") New in Django 6.0. * *class *AsyncPage(*object\_list*, *number*, *paginator*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L362)[¶](#django.core.paginator.AsyncPage "Link to this definition") Asynchronous version of [`Page`](#django.core.paginator.Page "django.core.paginator.Page"). `AsyncPage` has the same attributes and signatures as [`Page`](#django.core.paginator.Page "django.core.paginator.Page"), as well as asynchronous versions of all the same methods, using an `a` prefix - for example, use `await async_page.ahas_next()` rather than `page.has_next()`. `AsyncPage` has the following additional method: * aget\_object\_list()[¶](#django.core.paginator.AsyncPage.aget_object_list "Link to this definition") Returns `AsyncPage.object_list` as a list. This method must be awaited before `AsyncPage` can be treated as a sequence of `AsyncPage.object_list`. ## Exceptions[¶](#exceptions "Link to this heading") * *exception *InvalidPage[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L18)[¶](#django.core.paginator.InvalidPage "Link to this definition") A base class for exceptions raised when a paginator is passed an invalid page number. The [`Paginator.page()`](#django.core.paginator.Paginator.page "django.core.paginator.Paginator.page") method raises an exception if the requested page is invalid (i.e. not an integer) or contains no objects. Generally, it’s enough to catch the `InvalidPage` exception, but if you’d like more granularity, you can catch either of the following exceptions: * *exception *PageNotAnInteger[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L22)[¶](#django.core.paginator.PageNotAnInteger "Link to this definition") Raised when [`page()`](#django.core.paginator.Paginator.page "django.core.paginator.Paginator.page") is given a value that isn’t an integer. - *exception *EmptyPage[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/paginator.py#L26)[¶](#django.core.paginator.EmptyPage "Link to this definition") Raised when [`page()`](#django.core.paginator.Paginator.page "django.core.paginator.Paginator.page") is given a valid value but no objects exist on that page. Both of the exceptions are subclasses of [`InvalidPage`](#django.core.paginator.InvalidPage "django.core.paginator.InvalidPage"), so you can handle them both with `except InvalidPage`. [**Back to Top](#top) ## Additional Information ### Support Django! * [Panaton Software donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Paginator](#) * [`Paginator` class](#paginator-class) * [Methods](#methods) * [Attributes](#attributes) * [`AsyncPaginator` class](#asyncpaginator-class) * [`Page` class](#page-class) * [Methods](#id1) * [Attributes](#id2) * [`AsyncPage` class](#asyncpage-class) ---- url: https://docs.djangoproject.com/en/6.1/ref/contrib/postgres/operations/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/postgres/operations/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/contrib/postgres/operations/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/contrib/postgres/operations/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/contrib/postgres/operations/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/contrib/postgres/operations/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/contrib/postgres/operations/) - [it](https://docs.djangoproject.com/it/6.1/ref/contrib/postgres/operations/) - [id](https://docs.djangoproject.com/id/6.1/ref/contrib/postgres/operations/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/contrib/postgres/operations/) - [es](https://docs.djangoproject.com/es/6.1/ref/contrib/postgres/operations/) - [el](https://docs.djangoproject.com/el/6.1/ref/contrib/postgres/operations/) * * [dev](https://docs.djangoproject.com/en/dev/ref/contrib/postgres/operations/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/contrib/postgres/operations/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/contrib/postgres/operations/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/contrib/postgres/operations/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/contrib/postgres/operations/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/contrib/postgres/operations/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/contrib/postgres/operations/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/contrib/postgres/operations/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/contrib/postgres/operations/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/contrib/postgres/operations/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/operations/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/contrib/postgres/operations/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/contrib/postgres/operations/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/contrib/postgres/operations/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/contrib/postgres/operations/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/contrib/postgres/operations/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/contrib/postgres/operations/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/contrib/postgres/operations/) - [**](#top) # Database migration operations[¶](#database-migration-operations "Link to this heading") All of these [operations](../../../migration-operations/) are available from the `django.contrib.postgres.operations` module. ## Creating extension using migrations[¶](#creating-extension-using-migrations "Link to this heading") You can create a PostgreSQL extension in your database using a migration file. This example creates an hstore extension, but the same principles apply for other extensions. Set up the hstore extension in PostgreSQL before the first `CreateModel` or `AddField` operation that involves [`HStoreField`](../fields/#django.contrib.postgres.fields.HStoreField "django.contrib.postgres.fields.HStoreField") by adding a migration with the [`HStoreExtension`](#django.contrib.postgres.operations.HStoreExtension "django.contrib.postgres.operations.HStoreExtension") operation. For example: ``` from django.contrib.postgres.operations import HStoreExtension class Migration(migrations.Migration): ... operations = [HStoreExtension(), ...] ``` The operation skips adding the extension if it already exists. For most extensions, this requires a database user with superuser privileges. If the Django database user doesn’t have the appropriate privileges, you’ll have to create the extension outside of Django migrations with a user that has them. In that case, connect to your Django database and run the query `CREATE EXTENSION IF NOT EXISTS hstore;`. ## `CreateExtension`[¶](#createextension "Link to this heading") * *class *CreateExtension(*name*, *hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L12)[¶](#django.contrib.postgres.operations.CreateExtension "Link to this definition") An `Operation` subclass which installs a PostgreSQL extension. For common extensions, use one of the more specific subclasses below. * name[¶](#django.contrib.postgres.operations.CreateExtension.name "Link to this definition") This is a required argument. The name of the extension to be installed. - hints[¶](#django.contrib.postgres.operations.CreateExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## `BloomExtension`[¶](#bloomextension "Link to this heading") * *class *BloomExtension(*hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L74)[¶](#django.contrib.postgres.operations.BloomExtension "Link to this definition") Installs the `bloom` extension. * hints[¶](#django.contrib.postgres.operations.BloomExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## `BtreeGinExtension`[¶](#btreeginextension "Link to this heading") * *class *BtreeGinExtension(*hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L79)[¶](#django.contrib.postgres.operations.BtreeGinExtension "Link to this definition") Installs the `btree_gin` extension. * hints[¶](#django.contrib.postgres.operations.BtreeGinExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## `BtreeGistExtension`[¶](#btreegistextension "Link to this heading") * *class *BtreeGistExtension(*hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L84)[¶](#django.contrib.postgres.operations.BtreeGistExtension "Link to this definition") Installs the `btree_gist` extension. * hints[¶](#django.contrib.postgres.operations.BtreeGistExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## `CITextExtension`[¶](#citextextension "Link to this heading") * *class *CITextExtension(*hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L89)[¶](#django.contrib.postgres.operations.CITextExtension "Link to this definition") Installs the `citext` extension. * hints[¶](#django.contrib.postgres.operations.CITextExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## `CryptoExtension`[¶](#cryptoextension "Link to this heading") * *class *CryptoExtension(*hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L94)[¶](#django.contrib.postgres.operations.CryptoExtension "Link to this definition") Installs the `pgcrypto` extension. * hints[¶](#django.contrib.postgres.operations.CryptoExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## `HStoreExtension`[¶](#hstoreextension "Link to this heading") * *class *HStoreExtension(*hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L99)[¶](#django.contrib.postgres.operations.HStoreExtension "Link to this definition") Installs the `hstore` extension and also sets up the connection to interpret hstore data for possible use in subsequent migrations. * hints[¶](#django.contrib.postgres.operations.HStoreExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## `TrigramExtension`[¶](#trigramextension "Link to this heading") * *class *TrigramExtension(*hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L104)[¶](#django.contrib.postgres.operations.TrigramExtension "Link to this definition") Installs the `pg_trgm` extension. * hints[¶](#django.contrib.postgres.operations.TrigramExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## `UnaccentExtension`[¶](#unaccentextension "Link to this heading") * *class *UnaccentExtension(*hints=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L109)[¶](#django.contrib.postgres.operations.UnaccentExtension "Link to this definition") Installs the `unaccent` extension. * hints[¶](#django.contrib.postgres.operations.UnaccentExtension.hints "Link to this definition") New in Django 6.0. The optional `hints` argument will be passed as `**hints` to the [`allow_migrate()`](../../../../topics/db/multi-db/#allow_migrate "allow_migrate") method of database routers to assist them in [making routing decisions](../../../../topics/db/multi-db/#topics-db-multi-db-hints). ## Managing collations using migrations[¶](#managing-collations-using-migrations "Link to this heading") If you need to filter or order a column using a particular collation that your operating system provides but PostgreSQL does not, you can manage collations in your database using a migration file. These collations can then be used with the `db_collation` parameter on [`CharField`](../../../models/fields/#django.db.models.CharField "django.db.models.CharField"), [`TextField`](../../../models/fields/#django.db.models.TextField "django.db.models.TextField"), and their subclasses. For example, to create a collation for German phone book ordering: ``` from django.contrib.postgres.operations import CreateCollation class Migration(migrations.Migration): ... operations = [ CreateCollation( "case_insensitive", provider="icu", locale="und-u-ks-level2", deterministic=False, ), ..., ] ``` * *class *CreateCollation(*name*, *locale*, *\**, *provider='libc'*, *deterministic=True*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L219)[¶](#django.contrib.postgres.operations.CreateCollation "Link to this definition") Creates a collation with the given `name`, `locale` and `provider`. Set the `deterministic` parameter to `False` to create a non-deterministic collation, such as for case-insensitive filtering. - *class *RemoveCollation(*name*, *locale*, *\**, *provider='libc'*, *deterministic=True*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L249)[¶](#django.contrib.postgres.operations.RemoveCollation "Link to this definition") Removes the collations named `name`. When reversed this is creating a collation with the provided `locale`, `provider`, and `deterministic` arguments. Therefore, `locale` is required to make this operation reversible. ## Concurrent index operations[¶](#concurrent-index-operations "Link to this heading") PostgreSQL supports the `CONCURRENTLY` option to `CREATE INDEX` and `DROP INDEX` statements to add and remove indexes without locking out writes. This option is useful for adding or removing an index in a live production database. * *class *AddIndexConcurrently(*model\_name*, *index*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L123)[¶](#django.contrib.postgres.operations.AddIndexConcurrently "Link to this definition") Like [`AddIndex`](../../../migration-operations/#django.db.migrations.operations.AddIndex "django.db.migrations.operations.AddIndex"), but creates an index with the `CONCURRENTLY` option. This has a few caveats to be aware of when using this option, see [the PostgreSQL documentation of building indexes concurrently](https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY). - *class *RemoveIndexConcurrently(*model\_name*, *name*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L149)[¶](#django.contrib.postgres.operations.RemoveIndexConcurrently "Link to this definition") Like [`RemoveIndex`](../../../migration-operations/#django.db.migrations.operations.RemoveIndex "django.db.migrations.operations.RemoveIndex"), but removes the index with the `CONCURRENTLY` option. This has a few caveats to be aware of when using this option, see [the PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-dropindex.html). Note The `CONCURRENTLY` option is not supported inside a transaction (see [non-atomic migration](../../../../howto/writing-migrations/#non-atomic-migrations)). ## Adding constraints without enforcing validation[¶](#adding-constraints-without-enforcing-validation "Link to this heading") PostgreSQL supports the `NOT VALID` option with the `ADD CONSTRAINT` statement to add check constraints without enforcing validation on existing rows. This option is useful if you want to skip the potentially lengthy scan of the table to verify that all existing rows satisfy the constraint. To validate check constraints created with the `NOT VALID` option at a later point of time, use the [`ValidateConstraint`](#django.contrib.postgres.operations.ValidateConstraint "django.contrib.postgres.operations.ValidateConstraint") operation. See [the PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-NOTES) for more details. * *class *AddConstraintNotValid(*model\_name*, *constraint*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L274)[¶](#django.contrib.postgres.operations.AddConstraintNotValid "Link to this definition") Like [`AddConstraint`](../../../migration-operations/#django.db.migrations.operations.AddConstraint "django.db.migrations.operations.AddConstraint"), but avoids validating the constraint on existing rows. - *class *ValidateConstraint(*model\_name*, *name*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/operations.py#L310)[¶](#django.contrib.postgres.operations.ValidateConstraint "Link to this definition") Scans through the table and validates the given check constraint on existing rows. Note `AddConstraintNotValid` and `ValidateConstraint` operations should be performed in two separate migrations. Performing both operations in the same atomic migration has the same effect as [`AddConstraint`](../../../migration-operations/#django.db.migrations.operations.AddConstraint "django.db.migrations.operations.AddConstraint"), whereas performing them in a single non-atomic migration, may leave your database in an inconsistent state if the `ValidateConstraint` operation fails. [**Back to Top](#top) ## Additional Information ### Support Django! * [Hannes Struß donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Database migration operations](#) * [Creating extension using migrations](#creating-extension-using-migrations) * [`CreateExtension`](#createextension) * [`BloomExtension`](#bloomextension) * [`BtreeGinExtension`](#btreeginextension) * [`BtreeGistExtension`](#btreegistextension) * [`CITextExtension`](#citextextension) * [`CryptoExtension`](#cryptoextension) * [`HStoreExtension`](#hstoreextension) * [`TrigramExtension`](#trigramextension) * [`UnaccentExtension`](#unaccentextension) * [Managing collations using migrations](#managing-collations-using-migrations) * [Concurrent index operations](#concurrent-index-operations) * [Adding constraints without enforcing validation](#adding-constraints-without-enforcing-validation) ---- url: https://docs.djangoproject.com/en/6.1/releases/3.0.10/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/3.0.10/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/3.0.10/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/3.0.10/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/3.0.10/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/3.0.10/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/3.0.10/) - [it](https://docs.djangoproject.com/it/6.1/releases/3.0.10/) - [id](https://docs.djangoproject.com/id/6.1/releases/3.0.10/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/3.0.10/) - [es](https://docs.djangoproject.com/es/6.1/releases/3.0.10/) - [el](https://docs.djangoproject.com/el/6.1/releases/3.0.10/) * * [dev](https://docs.djangoproject.com/en/dev/releases/3.0.10/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/3.0.10/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/3.0.10/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/3.0.10/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/3.0.10/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/3.0.10/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/3.0.10/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/3.0.10/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/3.0.10/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/3.0.10/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/3.0.10/) - [**](#top) # Django 3.0.10 release notes[¶](#django-3-0-10-release-notes "Link to this heading") *September 1, 2020* Django 3.0.10 fixes two security issues and two data loss bugs in 3.0.9. * [confirm IT solutions donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 3.0.10 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.11.21/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.11.21/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.11.21/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.11.21/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.11.21/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.11.21/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.11.21/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.11.21/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.11.21/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.11.21/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.11.21/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.11.21/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.11.21/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.11.21/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.11.21/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.11.21/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.11.21/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.11.21/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.11.21/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.11.21/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.11.21/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.11.21/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.11.21/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.11.21/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.11.21/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.11.21/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.11.21/) - [**](#top) # Django 1.11.21 release notes[¶](#django-1-11-21-release-notes "Link to this heading") *June 3, 2019* Django 1.11.21 fixes a security issue in 1.11.20. ## CVE-2019-12308: AdminURLFieldWidget XSS[¶](#cve-2019-12308-adminurlfieldwidget-xss "Link to this heading") The clickable “Current URL” link generated by `AdminURLFieldWidget` displayed the provided value without validating it as a safe URL. Thus, an unvalidated value stored in the database, or a value provided as a URL query parameter payload, could result in an clickable JavaScript link. `AdminURLFieldWidget` now validates the provided value using [`URLValidator`](../../ref/validators/#django.core.validators.URLValidator "django.core.validators.URLValidator") before displaying the clickable link. You may customize the validator by passing a `validator_class` kwarg to `AdminURLFieldWidget.__init__()`, e.g. when using [`formfield_overrides`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.formfield_overrides "django.contrib.admin.ModelAdmin.formfield_overrides"). [**Back to Top](#top) ## Additional Information ### Support Django! * [Bolton Studios LLC donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.11.21 release notes](#) * [CVE-2019-12308: AdminURLFieldWidget XSS](#cve-2019-12308-adminurlfieldwidget-xss) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.11.7/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.11.7/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.11.7/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.11.7/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.11.7/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.11.7/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.11.7/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.11.7/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.11.7/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.11.7/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.11.7/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.11.7/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.11.7/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.11.7/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.11.7/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.11.7/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.11.7/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.11.7/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.11.7/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.11.7/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.11.7/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.11.7/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.11.7/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.11.7/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.11.7/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.11.7/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.11.7/) - [**](#top) # Django 1.11.7 release notes[¶](#django-1-11-7-release-notes "Link to this heading") *November 1, 2017* Django 1.11.7 fixes several bugs in 1.11.6. ## Bugfixes[¶](#bugfixes "Link to this heading") * Prevented `cache.get_or_set()` from caching `None` if the `default` argument is a callable that returns `None` ([#28601](https://code.djangoproject.com/ticket/28601)). * Fixed the Basque `DATE_FORMAT` string ([#28710](https://code.djangoproject.com/ticket/28710)). * Made `QuerySet.reverse()` affect `nulls_first` and `nulls_last` ([#28722](https://code.djangoproject.com/ticket/28722)). * Fixed unquoted table names in `Subquery` SQL when using `OuterRef` ([#28689](https://code.djangoproject.com/ticket/28689)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Djangojobs.Net donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.11.7 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.5.9/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.5.9/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.5.9/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.5.9/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.5.9/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.5.9/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.5.9/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.5.9/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.5.9/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.5.9/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.5.9/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.5.9/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.5.9/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.5.9/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.5.9/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.5.9/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.5.9/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.5.9/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.5.9/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.5.9/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.5.9/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.5.9/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.5.9/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.5.9/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.5.9/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.5.9/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.5.9/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.5.9/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.5.9/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.5.9/) - [**](#top) # Django 1.5.9 release notes[¶](#django-1-5-9-release-notes "Link to this heading") *August 20, 2014* Django 1.5.9 fixes several security issues in 1.5.8. * [Bors LTD donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.5.9 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.9/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.9/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.9/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.9/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.9/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.9/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.9/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.9/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.9/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.9/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.9/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.9/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.9/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.9/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.9/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.9/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.9/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.9/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.9/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.9/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.9/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.9/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.9/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.9/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.9/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.9/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.9/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.9/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.9/) - [**](#top) # Django 1.9 release notes[¶](#django-1-9-release-notes "Link to this heading") *December 1, 2015* Welcome to Django 1.9! These release notes cover the [new features](#whats-new-1-9), as well as some [backwards incompatible changes](#backwards-incompatible-1-9) you’ll want to be aware of when upgrading from Django 1.8 or older versions. We’ve [dropped some features](#removed-features-1-9) that have reached the end of their deprecation cycle, and we’ve [begun the deprecation process for some features](#deprecated-features-1-9). See the [How to upgrade Django to a newer version](../../howto/upgrade-version/) guide if you’re updating an existing project. ## Python compatibility[¶](#python-compatibility "Link to this heading") Django 1.9 requires Python 2.7, 3.4, or 3.5. We **highly recommend** and only officially support the latest release of each series. The Django 1.8 series is the last to support Python 3.2 and 3.3. ## What’s new in Django 1.9[¶](#what-s-new-in-django-1-9 "Link to this heading") ### Performing actions after a transaction commit[¶](#performing-actions-after-a-transaction-commit "Link to this heading") The new [`on_commit()`](../../topics/db/transactions/#django.db.transaction.on_commit "django.db.transaction.on_commit") hook allows performing actions after a database transaction is successfully committed. This is useful for tasks such as sending notification emails, creating queued tasks, or invalidating caches. This functionality from the [django-transaction-hooks](https://pypi.org/project/django-transaction-hooks/) package has been integrated into Django. ### Password validation[¶](#password-validation "Link to this heading") Django now offers password validation to help prevent the usage of weak passwords by users. The validation is integrated in the included password change and reset forms and is simple to integrate in any other code. Validation is performed by one or more validators, configured in the new [`AUTH_PASSWORD_VALIDATORS`](../../ref/settings/#std-setting-AUTH_PASSWORD_VALIDATORS) setting. Four validators are included in Django, which can enforce a minimum length, compare the password to the user’s attributes like their name, ensure passwords aren’t entirely numeric, or check against an included list of common passwords. You can combine multiple validators, and some validators have custom configuration options. For example, you can choose to provide a custom list of common passwords. Each validator provides a help text to explain its requirements to the user. By default, no validation is performed and all passwords are accepted, so if you don’t set [`AUTH_PASSWORD_VALIDATORS`](../../ref/settings/#std-setting-AUTH_PASSWORD_VALIDATORS), you will not see any change. In new projects created with the default [`startproject`](../../ref/django-admin/#django-admin-startproject) template, a simple set of validators is enabled. To enable basic validation in the included auth forms for your project, you could set, for example: ``` AUTH_PASSWORD_VALIDATORS = [ { "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator", }, { "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator", }, { "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator", }, { "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator", }, ] ``` See [Password validation](../../topics/auth/passwords/#password-validation) for more details. ### Permission mixins for class-based views[¶](#permission-mixins-for-class-based-views "Link to this heading") Django now ships with the mixins [`AccessMixin`](../../topics/auth/default/#django.contrib.auth.mixins.AccessMixin "django.contrib.auth.mixins.AccessMixin"), [`LoginRequiredMixin`](../../topics/auth/default/#django.contrib.auth.mixins.LoginRequiredMixin "django.contrib.auth.mixins.LoginRequiredMixin"), [`PermissionRequiredMixin`](../../topics/auth/default/#django.contrib.auth.mixins.PermissionRequiredMixin "django.contrib.auth.mixins.PermissionRequiredMixin"), and [`UserPassesTestMixin`](../../topics/auth/default/#django.contrib.auth.mixins.UserPassesTestMixin "django.contrib.auth.mixins.UserPassesTestMixin") to provide the functionality of the `django.contrib.auth.decorators` for class-based views. These mixins have been taken from, or are at least inspired by, the [django-braces](https://django-braces.readthedocs.io/en/latest/index.html) project. There are a few differences between Django’s and `django-braces`' implementation, though: * The [`raise_exception`](../../topics/auth/default/#django.contrib.auth.mixins.AccessMixin.raise_exception "django.contrib.auth.mixins.AccessMixin.raise_exception") attribute can only be `True` or `False`. Custom exceptions or callables are not supported. * The [`handle_no_permission()`](../../topics/auth/default/#django.contrib.auth.mixins.AccessMixin.handle_no_permission "django.contrib.auth.mixins.AccessMixin.handle_no_permission") method does not take a `request` argument. The current request is available in `self.request`. * The custom `test_func()` of [`UserPassesTestMixin`](../../topics/auth/default/#django.contrib.auth.mixins.UserPassesTestMixin "django.contrib.auth.mixins.UserPassesTestMixin") does not take a `user` argument. The current user is available in `self.request.user`. * The [`permission_required`](../../topics/auth/default/#django.contrib.auth.mixins.PermissionRequiredMixin "django.contrib.auth.mixins.PermissionRequiredMixin") attribute supports a string (defining one permission) or a list/tuple of strings (defining multiple permissions) that need to be fulfilled to grant access. * The new [`permission_denied_message`](../../topics/auth/default/#django.contrib.auth.mixins.AccessMixin.permission_denied_message "django.contrib.auth.mixins.AccessMixin.permission_denied_message") attribute allows passing a message to the `PermissionDenied` exception. ### New styling for `contrib.admin`[¶](#new-styling-for-contrib-admin "Link to this heading") The admin sports a modern, flat design with new SVG icons which look perfect on HiDPI screens. It still provides a fully-functional experience to [YUI’s A-grade](https://github.com/yui/yui3/wiki/Graded-Browser-Support) browsers. Older browser may experience varying levels of graceful degradation. ### Running tests in parallel[¶](#running-tests-in-parallel "Link to this heading") The [`test`](../../ref/django-admin/#django-admin-test) command now supports a [`--parallel`](../../ref/django-admin/#cmdoption-test-parallel) option to run a project’s tests in multiple processes in parallel. Each process gets its own database. You must ensure that different test cases don’t access the same resources. For instance, test cases that touch the filesystem should create a temporary directory for their own use. This option is enabled by default for Django’s own test suite provided: * the OS supports it (all but Windows) * the database backend supports it (all the built-in backends but Oracle) ### Minor features[¶](#minor-features "Link to this heading") #### [`django.contrib.admin`](../../ref/contrib/admin/#module-django.contrib.admin "django.contrib.admin: Django's admin site.")[¶](#django-contrib-admin "Link to this heading") * Admin views now have `model_admin` or `admin_site` attributes. * The URL of the admin change view has been changed (was at `/admin////` by default and is now at `/admin////change/`). This should not affect your application unless you have hardcoded admin URLs. In that case, replace those links by [reversing admin URLs](../../ref/contrib/admin/#admin-reverse-urls) instead. Note that the old URL still redirects to the new one for backwards compatibility, but it may be removed in a future version. * [`ModelAdmin.get_list_select_related()`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.get_list_select_related "django.contrib.admin.ModelAdmin.get_list_select_related") was added to allow changing the `select_related()` values used in the admin’s changelist query based on the request. * The `available_apps` context variable, which lists the available applications for the current user, has been added to the [`AdminSite.each_context()`](../../ref/contrib/admin/#django.contrib.admin.AdminSite.each_context "django.contrib.admin.AdminSite.each_context") method. * [`AdminSite.empty_value_display`](../../ref/contrib/admin/#django.contrib.admin.AdminSite.empty_value_display "django.contrib.admin.AdminSite.empty_value_display") and [`ModelAdmin.empty_value_display`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.empty_value_display "django.contrib.admin.ModelAdmin.empty_value_display") were added to override the display of empty values in admin change list. You can also customize the value for each field. * Added jQuery events [when an inline form is added or removed](../../ref/contrib/admin/javascript/#admin-javascript-inline-form-events) on the change form page. * The time picker widget includes a ‘6 p.m’ option for consistency of having predefined options every 6 hours. * JavaScript slug generation now supports Romanian characters. #### [`django.contrib.admindocs`](../../ref/contrib/admin/admindocs/#module-django.contrib.admindocs "django.contrib.admindocs: Django's admin documentation generator.")[¶](#django-contrib-admindocs "Link to this heading") * The model section of the `admindocs` now also describes methods that take arguments, rather than ignoring them. #### [`django.contrib.auth`](../../topics/auth/#module-django.contrib.auth "django.contrib.auth: Django's authentication framework.")[¶](#django-contrib-auth "Link to this heading") * The default iteration count for the PBKDF2 password hasher has been increased by 20%. This backwards compatible change will not affect users who have subclassed `django.contrib.auth.hashers.PBKDF2PasswordHasher` to change the default value. * The `BCryptSHA256PasswordHasher` will now update passwords if its `rounds` attribute is changed. * `AbstractBaseUser` and `BaseUserManager` were moved to a new `django.contrib.auth.base_user` module so that they can be imported without including `django.contrib.auth` in [`INSTALLED_APPS`](../../ref/settings/#std-setting-INSTALLED_APPS) (doing so raised a deprecation warning in older versions and is no longer supported in Django 1.9). * The permission argument of [`permission_required()`](../../topics/auth/default/#django.contrib.auth.decorators.permission_required "django.contrib.auth.decorators.permission_required") accepts all kinds of iterables, not only list and tuples. * The new [`PersistentRemoteUserMiddleware`](../../ref/middleware/#django.contrib.auth.middleware.PersistentRemoteUserMiddleware "django.contrib.auth.middleware.PersistentRemoteUserMiddleware") makes it possible to use `REMOTE_USER` for setups where the header is only populated on login pages instead of every request in the session. * The `django.contrib.auth.views.password_reset()` view accepts an `extra_email_context` parameter. #### [`django.contrib.contenttypes`](../../ref/contrib/contenttypes/#module-django.contrib.contenttypes "django.contrib.contenttypes: Provides generic interface to installed models.")[¶](#django-contrib-contenttypes "Link to this heading") * It’s now possible to use [`order_with_respect_to`](../../ref/models/options/#django.db.models.Options.order_with_respect_to "django.db.models.Options.order_with_respect_to") with a `GenericForeignKey`. #### [`django.contrib.gis`](../../ref/contrib/gis/#module-django.contrib.gis "django.contrib.gis: Geographic Information System (GIS) extensions for Django")[¶](#django-contrib-gis "Link to this heading") * All `GeoQuerySet` methods have been deprecated and replaced by [equivalent database functions](../../ref/contrib/gis/functions/). As soon as the legacy methods have been replaced in your code, you should even be able to remove the special `GeoManager` from your GIS-enabled classes. * The GDAL interface now supports instantiating file-based and in-memory [GDALRaster objects](../../ref/contrib/gis/gdal/#raster-data-source-objects) from raw data. Setters for raster properties such as projection or pixel values have been added. * For PostGIS users, the new [`RasterField`](../../ref/contrib/gis/model-api/#django.contrib.gis.db.models.RasterField "django.contrib.gis.db.models.RasterField") allows [storing GDALRaster objects](../../ref/contrib/gis/db-api/#creating-and-saving-raster-models). It supports automatic spatial index creation and reprojection when saving a model. It does not yet support spatial querying. * The new [`GDALRaster.warp()`](../../ref/contrib/gis/gdal/#django.contrib.gis.gdal.GDALRaster.warp "django.contrib.gis.gdal.GDALRaster.warp") method allows warping a raster by specifying target raster properties such as origin, width, height, or pixel size (among others). * The new [`GDALRaster.transform()`](../../ref/contrib/gis/gdal/#django.contrib.gis.gdal.GDALRaster.transform "django.contrib.gis.gdal.GDALRaster.transform") method allows transforming a raster into a different spatial reference system by specifying a target `srid`. * The new [`GeoIP2`](../../ref/contrib/gis/geoip2/#django.contrib.gis.geoip2.GeoIP2 "django.contrib.gis.geoip2.GeoIP2") class allows using MaxMind’s GeoLite2 databases which includes support for IPv6 addresses. * The default OpenLayers library version included in widgets has been updated from 2.13 to 2.13.1. #### [`django.contrib.postgres`](../../ref/contrib/postgres/#module-django.contrib.postgres "django.contrib.postgres: PostgreSQL-specific fields and features")[¶](#django-contrib-postgres "Link to this heading") * Added support for the [`rangefield.contained_by`](../../ref/contrib/postgres/fields/#std-fieldlookup-rangefield.contained_by) lookup for some built in fields which correspond to the range fields. * Added `django.contrib.postgres.fields.JSONField`. * Added [PostgreSQL specific aggregation functions](../../ref/contrib/postgres/aggregates/). * Added the [`TransactionNow`](../../ref/contrib/postgres/functions/#django.contrib.postgres.functions.TransactionNow "django.contrib.postgres.functions.TransactionNow") database function. #### [`django.contrib.sessions`](../../topics/http/sessions/#module-django.contrib.sessions "django.contrib.sessions: Provides session management for Django projects.")[¶](#django-contrib-sessions "Link to this heading") * The session model and `SessionStore` classes for the `db` and `cached_db` backends are refactored to allow a custom database session backend to build upon them. See [Extending database-backed session engines](../../topics/http/sessions/#extending-database-backed-session-engines) for more details. #### [`django.contrib.sites`](../../ref/contrib/sites/#module-django.contrib.sites "django.contrib.sites: Lets you operate multiple websites from the same database and Django project")[¶](#django-contrib-sites "Link to this heading") * [`get_current_site()`](../../ref/contrib/sites/#django.contrib.sites.shortcuts.get_current_site "django.contrib.sites.shortcuts.get_current_site") now handles the case where `request.get_host()` returns `domain:port`, e.g. `example.com:80`. If the lookup fails because the host does not match a record in the database and the host has a port, the port is stripped and the lookup is retried with the domain part only. #### [`django.contrib.syndication`](../../ref/contrib/syndication/#module-django.contrib.syndication "django.contrib.syndication: A framework for generating syndication feeds, in RSS and Atom, quite easily.")[¶](#django-contrib-syndication "Link to this heading") * Support for multiple enclosures per feed item has been added. If multiple enclosures are defined on a RSS feed, an exception is raised as RSS feeds, unlike Atom feeds, do not support multiple enclosures per feed item. #### Cache[¶](#cache "Link to this heading") * `django.core.cache.backends.base.BaseCache` now has a `get_or_set()` method. * [`django.views.decorators.cache.never_cache()`](../../topics/http/decorators/#django.views.decorators.cache.never_cache "django.views.decorators.cache.never_cache") now sends more persuasive headers (added `no-cache, no-store, must-revalidate` to `Cache-Control`) to better prevent caching. This was also added in Django 1.8.8. #### CSRF[¶](#csrf "Link to this heading") * The request header’s name used for CSRF authentication can be customized with [`CSRF_HEADER_NAME`](../../ref/settings/#std-setting-CSRF_HEADER_NAME). * The CSRF referer header is now validated against the [`CSRF_COOKIE_DOMAIN`](../../ref/settings/#std-setting-CSRF_COOKIE_DOMAIN) setting if set. See [How it works](../../ref/csrf/#how-csrf-works) for details. * The new [`CSRF_TRUSTED_ORIGINS`](../../ref/settings/#std-setting-CSRF_TRUSTED_ORIGINS) setting provides a way to allow cross-origin unsafe requests (e.g. `POST`) over HTTPS. #### Database backends[¶](#database-backends "Link to this heading") * The PostgreSQL backend (`django.db.backends.postgresql_psycopg2`) is also available as `django.db.backends.postgresql`. The old name will continue to be available for backwards compatibility. #### File Storage[¶](#file-storage "Link to this heading") * [`Storage.get_valid_name()`](../../ref/files/storage/#django.core.files.storage.Storage.get_valid_name "django.core.files.storage.Storage.get_valid_name") is now called when the [`upload_to`](../../ref/models/fields/#django.db.models.FileField.upload_to "django.db.models.FileField.upload_to") is a callable. * [`File`](../../ref/files/file/#django.core.files.File "django.core.files.File") now has the `seekable()` method when using Python 3. #### Forms[¶](#forms "Link to this heading") * [`ModelForm`](../../topics/forms/modelforms/#django.forms.ModelForm "django.forms.ModelForm") accepts the new `Meta` option `field_classes` to customize the type of the fields. See [Overriding the default fields](../../topics/forms/modelforms/#modelforms-overriding-default-fields) for details. * You can now specify the order in which form fields are rendered with the [`field_order`](../../ref/forms/api/#django.forms.Form.field_order "django.forms.Form.field_order") attribute, the `field_order` constructor argument , or the [`order_fields()`](../../ref/forms/api/#django.forms.Form.order_fields "django.forms.Form.order_fields") method. * A form prefix can be specified inside a form class, not only when instantiating a form. See [Prefixes for forms](../../ref/forms/api/#form-prefix) for details. * You can now [specify keyword arguments](../../topics/forms/formsets/#custom-formset-form-kwargs) that you want to pass to the constructor of forms in a formset. * [`SlugField`](../../ref/forms/fields/#django.forms.SlugField "django.forms.SlugField") now accepts an [`allow_unicode`](../../ref/forms/fields/#django.forms.SlugField.allow_unicode "django.forms.SlugField.allow_unicode") argument to allow Unicode characters in slugs. * [`CharField`](../../ref/forms/fields/#django.forms.CharField "django.forms.CharField") now accepts a [`strip`](../../ref/forms/fields/#django.forms.CharField.strip "django.forms.CharField.strip") argument to strip input data of leading and trailing whitespace. As this defaults to `True` this is different behavior from previous releases. * Form fields now support the [`disabled`](../../ref/forms/fields/#django.forms.Field.disabled "django.forms.Field.disabled") argument, allowing the field widget to be displayed disabled by browsers. * It’s now possible to customize bound fields by overriding a field’s [`get_bound_field()`](../../ref/forms/fields/#django.forms.Field.get_bound_field "django.forms.Field.get_bound_field") method. #### Generic Views[¶](#generic-views "Link to this heading") * Class-based views generated using `as_view()` now have `view_class` and `view_initkwargs` attributes. * [`method_decorator()`](../../ref/utils/#django.utils.decorators.method_decorator "django.utils.decorators.method_decorator") can now be used with a list or tuple of decorators. It can also be used to [decorate classes instead of methods](../../topics/class-based-views/intro/#id1). #### Internationalization[¶](#internationalization "Link to this heading") * The [`django.views.i18n.set_language()`](../../topics/i18n/translation/#django.views.i18n.set_language "django.views.i18n.set_language") view now properly redirects to [translated URLs](../../topics/i18n/translation/#url-internationalization), when available. * The `django.views.i18n.javascript_catalog()` view now works correctly if used multiple times with different configurations on the same page. * The [`django.utils.timezone.make_aware()`](../../ref/utils/#django.utils.timezone.make_aware "django.utils.timezone.make_aware") function gained an `is_dst` argument to help resolve ambiguous times during DST transitions. * You can now use locale variants supported by gettext. These are usually used for languages which can be written in different scripts, for example Latin and Cyrillic (e.g. `be@latin`). * Added the `django.views.i18n.json_catalog()` view to help build a custom client-side i18n library upon Django translations. It returns a JSON object containing a translations catalog, formatting settings, and a plural rule. * Added the `name_translated` attribute to the object returned by the [`get_language_info`](../../topics/i18n/translation/#std-templatetag-get_language_info) template tag. Also added a corresponding template filter: [`language_name_translated`](../../topics/i18n/translation/#std-templatefilter-language_name_translated). * You can now run [`compilemessages`](../../ref/django-admin/#django-admin-compilemessages) from the root directory of your project and it will find all the app message files that were created by [`makemessages`](../../ref/django-admin/#django-admin-makemessages). * [`makemessages`](../../ref/django-admin/#django-admin-makemessages) now calls `xgettext` once per locale directory rather than once per translatable file. This speeds up localization builds. * [`blocktrans`](../../topics/i18n/translation/#std-templatetag-blocktrans) supports assigning its output to a variable using `asvar`. * Two new languages are available: Colombian Spanish and Scottish Gaelic. #### Management Commands[¶](#management-commands "Link to this heading") * The new [`sendtestemail`](../../ref/django-admin/#django-admin-sendtestemail) command lets you send a test email to easily confirm that email sending through Django is working. * To increase the readability of the SQL code generated by [`sqlmigrate`](../../ref/django-admin/#django-admin-sqlmigrate), the SQL code generated for each migration operation is preceded by the operation’s description. * The [`dumpdata`](../../ref/django-admin/#django-admin-dumpdata) command output is now deterministically ordered. Moreover, when the `--output` option is specified, it also shows a progress bar in the terminal. * The [`createcachetable`](../../ref/django-admin/#django-admin-createcachetable) command now has a `--dry-run` flag to print out the SQL rather than execute it. * The [`startapp`](../../ref/django-admin/#django-admin-startapp) command creates an `apps.py` file. Since it doesn’t use `default_app_config` ([a discouraged API](../../ref/applications/#configuring-applications-ref)), you must specify the app config’s path, e.g. `'polls.apps.PollsConfig'`, in [`INSTALLED_APPS`](../../ref/settings/#std-setting-INSTALLED_APPS) for it to be used (instead of just `'polls'`). * When using the PostgreSQL backend, the [`dbshell`](../../ref/django-admin/#django-admin-dbshell) command can connect to the database using the password from your settings file (instead of requiring it to be manually entered). * The `django` package may be run as a script, i.e. `python -m django`, which will behave the same as `django-admin`. * Management commands that have the `--noinput` option now also take `--no-input` as an alias for that option. #### Migrations[¶](#migrations "Link to this heading") * Initial migrations are now marked with an [`initial = True`](../../topics/migrations/#django.db.migrations.Migration.initial "django.db.migrations.Migration.initial") class attribute which allows [`migrate --fake-initial`](../../ref/django-admin/#cmdoption-migrate-fake-initial) to more easily detect initial migrations. * Added support for serialization of `functools.partial` and `LazyObject` instances. * When supplying `None` as a value in [`MIGRATION_MODULES`](../../ref/settings/#std-setting-MIGRATION_MODULES), Django will consider the app an app without migrations. * When applying migrations, the “Rendering model states” step that’s displayed when running migrate with verbosity 2 or higher now computes only the states for the migrations that have already been applied. The model states for migrations being applied are generated on demand, drastically reducing the amount of required memory. However, this improvement is not available when unapplying migrations and therefore still requires the precomputation and storage of the intermediate migration states. This improvement also requires that Django no longer supports mixed migration plans. Mixed plans consist of a list of migrations where some are being applied and others are being unapplied. This was never officially supported and never had a public API that supports this behavior. * The [`squashmigrations`](../../ref/django-admin/#django-admin-squashmigrations) command now supports specifying the starting migration from which migrations will be squashed. #### Models[¶](#models "Link to this heading") * [`QuerySet.bulk_create()`](../../ref/models/querysets/#django.db.models.query.QuerySet.bulk_create "django.db.models.query.QuerySet.bulk_create") now works on proxy models. * Database configuration gained a [`TIME_ZONE`](../../ref/settings/#std-setting-DATABASE-TIME_ZONE) option for interacting with databases that store datetimes in local time and don’t support time zones when [`USE_TZ`](../../ref/settings/#std-setting-USE_TZ) is `True`. * Added the [`RelatedManager.set()`](../../ref/models/relations/#django.db.models.fields.related.RelatedManager.set "django.db.models.fields.related.RelatedManager.set") method to the related managers created by `ForeignKey`, `GenericForeignKey`, and `ManyToManyField`. * The [`add()`](../../ref/models/relations/#django.db.models.fields.related.RelatedManager.add "django.db.models.fields.related.RelatedManager.add") method on a reverse foreign key now has a `bulk` parameter to allow executing one query regardless of the number of objects being added rather than one query per object. * Added the `keep_parents` parameter to [`Model.delete()`](../../ref/models/instances/#django.db.models.Model.delete "django.db.models.Model.delete") to allow deleting only a child’s data in a model that uses multi-table inheritance. * [`Model.delete()`](../../ref/models/instances/#django.db.models.Model.delete "django.db.models.Model.delete") and [`QuerySet.delete()`](../../ref/models/querysets/#django.db.models.query.QuerySet.delete "django.db.models.query.QuerySet.delete") return the number of objects deleted. * Added a system check to prevent defining both `Meta.ordering` and `order_with_respect_to` on the same model. * [`Date and time`](../../ref/models/querysets/#std-fieldlookup-year) lookups can be chained with other lookups (such as [`exact`](../../ref/models/querysets/#std-fieldlookup-exact), [`gt`](../../ref/models/querysets/#std-fieldlookup-gt), [`lt`](../../ref/models/querysets/#std-fieldlookup-lt), etc.). For example: `Entry.objects.filter(pub_date__month__gt=6)`. * Time lookups (hour, minute, second) are now supported by [`TimeField`](../../ref/models/fields/#django.db.models.TimeField "django.db.models.TimeField") for all database backends. Support for backends other than SQLite was added but undocumented in Django 1.7. * You can specify the `output_field` parameter of the [`Avg`](../../ref/models/querysets/#django.db.models.Avg "django.db.models.Avg") aggregate in order to aggregate over non-numeric columns, such as `DurationField`. * Added the [`date`](../../ref/models/querysets/#std-fieldlookup-date) lookup to [`DateTimeField`](../../ref/models/fields/#django.db.models.DateTimeField "django.db.models.DateTimeField") to allow querying the field by only the date portion. * Added the [`Greatest`](../../ref/models/database-functions/#django.db.models.functions.Greatest "django.db.models.functions.Greatest") and [`Least`](../../ref/models/database-functions/#django.db.models.functions.Least "django.db.models.functions.Least") database functions. * Added the [`Now`](../../ref/models/database-functions/#django.db.models.functions.Now "django.db.models.functions.Now") database function, which returns the current date and time. * [`Transform`](../../ref/models/lookups/#django.db.models.Transform "django.db.models.Transform") is now a subclass of [Func()](../../ref/models/expressions/#func-expressions) which allows `Transform`s to be used on the right hand side of an expression, just like regular `Func`s. This allows registering some database functions like [`Length`](../../ref/models/database-functions/#django.db.models.functions.Length "django.db.models.functions.Length"), [`Lower`](../../ref/models/database-functions/#django.db.models.functions.Lower "django.db.models.functions.Lower"), and [`Upper`](../../ref/models/database-functions/#django.db.models.functions.Upper "django.db.models.functions.Upper") as transforms. * [`SlugField`](../../ref/models/fields/#django.db.models.SlugField "django.db.models.SlugField") now accepts an [`allow_unicode`](../../ref/models/fields/#django.db.models.SlugField.allow_unicode "django.db.models.SlugField.allow_unicode") argument to allow Unicode characters in slugs. * Added support for referencing annotations in `QuerySet.distinct()`. * `connection.queries` shows queries with substituted parameters on SQLite. * [Query expressions](../../ref/models/expressions/) can now be used when creating new model instances using `save()`, `create()`, and `bulk_create()`. #### Requests and Responses[¶](#requests-and-responses "Link to this heading") * Unless [`HttpResponse.reason_phrase`](../../ref/request-response/#django.http.HttpResponse.reason_phrase "django.http.HttpResponse.reason_phrase") is explicitly set, it now is determined by the current value of [`HttpResponse.status_code`](../../ref/request-response/#django.http.HttpResponse.status_code "django.http.HttpResponse.status_code"). Modifying the value of `status_code` outside of the constructor will also modify the value of `reason_phrase`. * The debug view now shows details of chained exceptions on Python 3. * The default 40x error views now accept a second positional parameter, the exception that triggered the view. * View error handlers now support [`TemplateResponse`](../../ref/template-response/#django.template.response.TemplateResponse "django.template.response.TemplateResponse"), commonly used with class-based views. * Exceptions raised by the `render()` method are now passed to the `process_exception()` method of each middleware. * Request middleware can now set [`HttpRequest.urlconf`](../../ref/request-response/#django.http.HttpRequest.urlconf "django.http.HttpRequest.urlconf") to `None` to revert any changes made by previous middleware and return to using the [`ROOT_URLCONF`](../../ref/settings/#std-setting-ROOT_URLCONF). * The [`DISALLOWED_USER_AGENTS`](../../ref/settings/#std-setting-DISALLOWED_USER_AGENTS) check in [`CommonMiddleware`](../../ref/middleware/#django.middleware.common.CommonMiddleware "django.middleware.common.CommonMiddleware") now raises a [`PermissionDenied`](../../ref/exceptions/#django.core.exceptions.PermissionDenied "django.core.exceptions.PermissionDenied") exception as opposed to returning an [`HttpResponseForbidden`](../../ref/request-response/#django.http.HttpResponseForbidden "django.http.HttpResponseForbidden") so that [`handler403`](../../ref/urls/#django.conf.urls.handler403 "django.conf.urls.handler403") is invoked. * Added [`HttpRequest.get_port()`](../../ref/request-response/#django.http.HttpRequest.get_port "django.http.HttpRequest.get_port") to fetch the originating port of the request. * Added the `json_dumps_params` parameter to [`JsonResponse`](../../ref/request-response/#django.http.JsonResponse "django.http.JsonResponse") to allow passing keyword arguments to the `json.dumps()` call used to generate the response. * The [`BrokenLinkEmailsMiddleware`](../../ref/middleware/#django.middleware.common.BrokenLinkEmailsMiddleware "django.middleware.common.BrokenLinkEmailsMiddleware") now ignores 404s when the referer is equal to the requested URL. To circumvent the empty referer check already implemented, some web bots set the referer to the requested URL. #### Templates[¶](#templates "Link to this heading") * Template tags created with the [`simple_tag()`](../../howto/custom-template-tags/#django.template.Library.simple_tag "django.template.Library.simple_tag") helper can now store results in a template variable by using the `as` argument. * Added a [`Context.setdefault()`](../../ref/templates/api/#django.template.Context.setdefault "django.template.Context.setdefault") method. * The [django.template](../../ref/logging/#django-template-logger) logger was added and includes the following messages: * A `DEBUG` level message for missing context variables. * A `WARNING` level message for uncaught exceptions raised during the rendering of an `{% include %}` when debug mode is off (helpful since `{% include %}` silences the exception and returns an empty string). * The [`firstof`](../../ref/templates/builtins/#std-templatetag-firstof) template tag supports storing the output in a variable using ‘as’. * [`Context.update()`](../../ref/templates/api/#django.template.Context.update "django.template.Context.update") can now be used as a context manager. * Django template loaders can now extend templates recursively. * The debug page template postmortem now include output from each engine that is installed. * [Debug page integration](../../howto/custom-template-backend/#template-debug-integration) for custom template engines was added. * The [`DjangoTemplates`](../../topics/templates/#django.template.backends.django.DjangoTemplates "django.template.backends.django.DjangoTemplates") backend gained the ability to register libraries and builtins explicitly through the template [`OPTIONS`](../../ref/settings/#std-setting-TEMPLATES-OPTIONS). * The `timesince` and `timeuntil` filters were improved to deal with leap years when given large time spans. * The `include` tag now caches parsed templates objects during template rendering, speeding up reuse in places such as for loops. #### Tests[¶](#tests "Link to this heading") * Added the [`json()`](../../topics/testing/tools/#django.test.Response.json "django.test.Response.json") method to test client responses to give access to the response body as JSON. * Added the [`force_login()`](../../topics/testing/tools/#django.test.Client.force_login "django.test.Client.force_login") method to the test client. Use this method to simulate the effect of a user logging into the site while skipping the authentication and verification steps of [`login()`](../../topics/testing/tools/#django.test.Client.login "django.test.Client.login"). #### URLs[¶](#urls "Link to this heading") * Regular expression lookaround assertions are now allowed in URL patterns. * The application namespace can now be set using an `app_name` attribute on the included module or object. It can also be set by passing a 2-tuple of (\, \) as the first argument to `include()`. * System checks have been added for common URL pattern mistakes. #### Validators[¶](#validators "Link to this heading") * Added [`django.core.validators.int_list_validator()`](../../ref/validators/#django.core.validators.int_list_validator "django.core.validators.int_list_validator") to generate validators of strings containing integers separated with a custom character. * [`EmailValidator`](../../ref/validators/#django.core.validators.EmailValidator "django.core.validators.EmailValidator") now limits the length of domain name labels to 63 characters per [**RFC 1034**](https://datatracker.ietf.org/doc/html/rfc1034.html). * Added [`validate_unicode_slug()`](../../ref/validators/#django.core.validators.validate_unicode_slug "django.core.validators.validate_unicode_slug") to validate slugs that may contain Unicode characters. ## Backwards incompatible changes in 1.9[¶](#backwards-incompatible-changes-in-1-9 "Link to this heading") Warning In addition to the changes outlined in this section, be sure to review the [Features removed in 1.9](#removed-features-1-9) for the features that have reached the end of their deprecation cycle and therefore been removed. If you haven’t updated your code within the deprecation timeline for a given feature, its removal may appear as a backwards incompatible change. ### Database backend API[¶](#database-backend-api "Link to this heading") * A couple of new tests rely on the ability of the backend to introspect column defaults (returning the result as `Field.default`). You can set the `can_introspect_default` database feature to `False` if your backend doesn’t implement this. You may want to review the implementation on the backends that Django includes for reference ([#24245](https://code.djangoproject.com/ticket/24245)). * Registering a global adapter or converter at the level of the DB-API module to handle time zone information of [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") values passed as query parameters or returned as query results on databases that don’t support time zones is discouraged. It can conflict with other libraries. The recommended way to add a time zone to [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") values fetched from the database is to register a converter for `DateTimeField` in `DatabaseOperations.get_db_converters()`. The `needs_datetime_string_cast` database feature was removed. Database backends that set it must register a converter instead, as explained above. * The `DatabaseOperations.value_to_db_()` methods were renamed to `adapt_field_value()` to mirror the `convert_field_value()` methods. * To use the new `date` lookup, third-party database backends may need to implement the `DatabaseOperations.datetime_cast_date_sql()` method. * The `DatabaseOperations.time_extract_sql()` method was added. It calls the existing `date_extract_sql()` method. This method is overridden by the SQLite backend to add time lookups (hour, minute, second) to [`TimeField`](../../ref/models/fields/#django.db.models.TimeField "django.db.models.TimeField"), and may be needed by third-party database backends. * The `DatabaseOperations.datetime_cast_sql()` method (not to be confused with `DatabaseOperations.datetime_cast_date_sql()` mentioned above) has been removed. This method served to format dates on Oracle long before 1.0, but hasn’t been overridden by any core backend in years and hasn’t been called anywhere in Django’s code or tests. * In order to support test parallelization, you must implement the `DatabaseCreation._clone_test_db()` method and set `DatabaseFeatures.can_clone_databases = True`. You may have to adjust `DatabaseCreation.get_test_db_clone_settings()`. ### Default settings that were tuples are now lists[¶](#default-settings-that-were-tuples-are-now-lists "Link to this heading") The default settings in `django.conf.global_settings` were a combination of lists and tuples. All settings that were formerly tuples are now lists. ### `is_usable` attribute on template loaders is removed[¶](#is-usable-attribute-on-template-loaders-is-removed "Link to this heading") Django template loaders previously required an `is_usable` attribute to be defined. If a loader was configured in the template settings and this attribute was `False`, the loader would be silently ignored. In practice, this was only used by the egg loader to detect if `setuptools` was installed. The `is_usable` attribute is now removed and the egg loader instead fails at runtime if `setuptools` is not installed. ### Related set direct assignment[¶](#related-set-direct-assignment "Link to this heading") Direct assignment of related objects in the ORM used to perform a `clear()` followed by a call to `add()`. This caused needlessly large data changes and prevented using the [`m2m_changed`](../../ref/signals/#django.db.models.signals.m2m_changed "django.db.models.signals.m2m_changed") signal to track individual changes in many-to-many relations. Direct assignment now relies on the new [`set()`](../../ref/models/relations/#django.db.models.fields.related.RelatedManager.set "django.db.models.fields.related.RelatedManager.set") method on related managers which by default only processes changes between the existing related set and the one that’s newly assigned. The previous behavior can be restored by replacing direct assignment by a call to `set()` with the keyword argument `clear=True`. `ModelForm`, and therefore `ModelAdmin`, internally rely on direct assignment for many-to-many relations and as a consequence now use the new behavior. ### Filesystem-based template loaders catch more specific exceptions[¶](#filesystem-based-template-loaders-catch-more-specific-exceptions "Link to this heading") When using the [`filesystem.Loader`](../../ref/templates/api/#django.template.loaders.filesystem.Loader "django.template.loaders.filesystem.Loader") or [`app_directories.Loader`](../../ref/templates/api/#django.template.loaders.app_directories.Loader "django.template.loaders.app_directories.Loader") template loaders, earlier versions of Django raised a [`TemplateDoesNotExist`](../../topics/templates/#django.template.TemplateDoesNotExist "django.template.TemplateDoesNotExist") error if a template source existed but was unreadable. This could happen under many circumstances, such as if Django didn’t have permissions to open the file, or if the template source was a directory. Now, Django only silences the exception if the template source does not exist. All other situations result in the original `IOError` being raised. ### HTTP redirects no longer forced to absolute URIs[¶](#http-redirects-no-longer-forced-to-absolute-uris "Link to this heading") Relative redirects are no longer converted to absolute URIs. [**RFC 2616**](https://datatracker.ietf.org/doc/html/rfc2616.html) required the `Location` header in redirect responses to be an absolute URI, but it has been superseded by [**RFC 7231**](https://datatracker.ietf.org/doc/html/rfc7231.html) which allows relative URIs in `Location`, recognizing the actual practice of user agents, almost all of which support them. Consequently, the expected URLs passed to `assertRedirects` should generally no longer include the scheme and domain part of the URLs. For example, `self.assertRedirects(response, 'http://testserver/some-url/')` should be replaced by `self.assertRedirects(response, '/some-url/')` (unless the redirection specifically contained an absolute URL). In the rare case that you need the old behavior (discovered with an ancient version of Apache with `mod_scgi` that interprets a relative redirect as an “internal redirect”), you can restore it by writing a custom middleware: ``` class LocationHeaderFix(object): def process_response(self, request, response): if "Location" in response: response["Location"] = request.build_absolute_uri(response["Location"]) return response ``` ### Dropped support for PostgreSQL 9.0[¶](#dropped-support-for-postgresql-9-0 "Link to this heading") Upstream support for PostgreSQL 9.0 ended in September 2015. As a consequence, Django 1.9 sets 9.1 as the minimum PostgreSQL version it officially supports. ### Dropped support for Oracle 11.1[¶](#dropped-support-for-oracle-11-1 "Link to this heading") Upstream support for Oracle 11.1 ended in August 2015. As a consequence, Django 1.9 sets 11.2 as the minimum Oracle version it officially supports. ### Bulk behavior of `add()` method of related managers[¶](#bulk-behavior-of-add-method-of-related-managers "Link to this heading") To improve performance, the `add()` methods of the related managers created by `ForeignKey` and `GenericForeignKey` changed from a series of `Model.save()` calls to a single `QuerySet.update()` call. The change means that `pre_save` and `post_save` signals aren’t sent anymore. You can use the `bulk=False` keyword argument to revert to the previous behavior. ### Template `LoaderOrigin` and `StringOrigin` are removed[¶](#template-loaderorigin-and-stringorigin-are-removed "Link to this heading") In previous versions of Django, when a template engine was initialized with debug as `True`, an instance of `django.template.loader.LoaderOrigin` or `django.template.base.StringOrigin` was set as the origin attribute on the template object. These classes have been combined into [`Origin`](../../ref/templates/api/#django.template.base.Origin "django.template.base.Origin") and is now always set regardless of the engine debug setting. For a minimal level of backwards compatibility, the old class names will be kept as aliases to the new `Origin` class until Django 2.0. ### Changes to the default logging configuration[¶](#changes-to-the-default-logging-configuration "Link to this heading") To make it easier to write custom logging configurations, Django’s default logging configuration no longer defines `django.request` and `django.security` loggers. Instead, it defines a single `django` logger, filtered at the `INFO` level, with two handlers: * `console`: filtered at the `INFO` level and only active if `DEBUG=True`. * `mail_admins`: filtered at the `ERROR` level and only active if `DEBUG=False`. If you aren’t overriding Django’s default logging, you should see minimal changes in behavior, but you might see some new logging to the `runserver` console, for example. If you are overriding Django’s default logging, you should check to see how your configuration merges with the new defaults. ### `HttpRequest` details in error reporting[¶](#httprequest-details-in-error-reporting "Link to this heading") It was redundant to display the full details of the [`HttpRequest`](../../ref/request-response/#django.http.HttpRequest "django.http.HttpRequest") each time it appeared as a stack frame variable in the HTML version of the debug page and error email. Thus, the HTTP request will now display the same standard representation as other variables (`repr(request)`). As a result, the `ExceptionReporterFilter.get_request_repr()` method and the undocumented `django.http.build_request_repr()` function were removed. The contents of the text version of the email were modified to provide a traceback of the same structure as in the case of AJAX requests. The traceback details are rendered by the `ExceptionReporter.get_traceback_text()` method. ### Removal of time zone aware global adapters and converters for datetimes[¶](#removal-of-time-zone-aware-global-adapters-and-converters-for-datetimes "Link to this heading") Django no longer registers global adapters and converters for managing time zone information on [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") values sent to the database as query parameters or read from the database in query results. This change affects projects that meet all the following conditions: * The [`USE_TZ`](../../ref/settings/#std-setting-USE_TZ) setting is `True`. * The database is SQLite, MySQL, Oracle, or a third-party database that doesn’t support time zones. In doubt, you can check the value of `connection.features.supports_timezones`. * The code queries the database outside of the ORM, typically with `cursor.execute(sql, params)`. If you’re passing aware [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") parameters to such queries, you should turn them into naive datetimes in UTC: ``` from django.utils import timezone param = timezone.make_naive(param, timezone.utc) ``` If you fail to do so, the conversion will be performed as in earlier versions (with a deprecation warning) up until Django 1.11. Django 2.0 won’t perform any conversion, which may result in data corruption. If you’re reading [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") values from the results, they will be naive instead of aware. You can compensate as follows: ``` from django.utils import timezone value = timezone.make_aware(value, timezone.utc) ``` You don’t need any of this if you’re querying the database through the ORM, even if you’re using [`raw()`](../../ref/models/querysets/#django.db.models.query.QuerySet.raw "django.db.models.query.QuerySet.raw") queries. The ORM takes care of managing time zone information. ### Template tag modules are imported when templates are configured[¶](#template-tag-modules-are-imported-when-templates-are-configured "Link to this heading") The [`DjangoTemplates`](../../topics/templates/#django.template.backends.django.DjangoTemplates "django.template.backends.django.DjangoTemplates") backend now performs discovery on installed template tag modules when instantiated. This update enables libraries to be provided explicitly via the `'libraries'` key of [`OPTIONS`](../../ref/settings/#std-setting-TEMPLATES-OPTIONS) when defining a [`DjangoTemplates`](../../topics/templates/#django.template.backends.django.DjangoTemplates "django.template.backends.django.DjangoTemplates") backend. Import or syntax errors in template tag modules now fail early at instantiation time rather than when a template with a [`{% load %}`](../../ref/templates/builtins/#std-templatetag-load) tag is first compiled. ### `django.template.base.add_to_builtins()` is removed[¶](#django-template-base-add-to-builtins-is-removed "Link to this heading") Although it was a private API, projects commonly used `add_to_builtins()` to make template tags and filters available without using the [`{% load %}`](../../ref/templates/builtins/#std-templatetag-load) tag. This API has been formalized. Projects should now define built-in libraries via the `'builtins'` key of [`OPTIONS`](../../ref/settings/#std-setting-TEMPLATES-OPTIONS) when defining a [`DjangoTemplates`](../../topics/templates/#django.template.backends.django.DjangoTemplates "django.template.backends.django.DjangoTemplates") backend. ### `simple_tag` now wraps tag output in `conditional_escape`[¶](#simple-tag-now-wraps-tag-output-in-conditional-escape "Link to this heading") In general, template tags do not autoescape their contents, and this behavior is [documented](../../howto/custom-template-tags/#tags-auto-escaping). For tags like [`inclusion_tag`](../../howto/custom-template-tags/#django.template.Library.inclusion_tag "django.template.Library.inclusion_tag"), this is not a problem because the included template will perform autoescaping. For `assignment_tag()`, the output will be escaped when it is used as a variable in the template. For the intended use cases of [`simple_tag`](../../howto/custom-template-tags/#django.template.Library.simple_tag "django.template.Library.simple_tag"), however, it is very easy to end up with incorrect HTML and possibly an XSS exploit. For example: ``` @register.simple_tag(takes_context=True) def greeting(context): return "Hello {0}!".format(context["request"].user.first_name) ``` In older versions of Django, this will be an XSS issue because `user.first_name` is not escaped. In Django 1.9, this is fixed: if the template context has `autoescape=True` set (the default), then `simple_tag` will wrap the output of the tag function with [`conditional_escape()`](../../ref/utils/#django.utils.html.conditional_escape "django.utils.html.conditional_escape"). To fix your `simple_tag`s, it is best to apply the following practices: * Any code that generates HTML should use either the template system or [`format_html()`](../../ref/utils/#django.utils.html.format_html "django.utils.html.format_html"). * If the output of a `simple_tag` needs escaping, use [`escape()`](../../ref/utils/#django.utils.html.escape "django.utils.html.escape") or [`conditional_escape()`](../../ref/utils/#django.utils.html.conditional_escape "django.utils.html.conditional_escape"). * If you are absolutely certain that you are outputting HTML from a trusted source (e.g. a CMS field that stores HTML entered by admins), you can mark it as such using [`mark_safe()`](../../ref/utils/#django.utils.safestring.mark_safe "django.utils.safestring.mark_safe"). Tags that follow these rules will be correct and safe whether they are run on Django 1.9+ or earlier. ### `Paginator.page_range`[¶](#paginator-page-range "Link to this heading") [`Paginator.page_range`](../../ref/paginator/#django.core.paginator.Paginator.page_range "django.core.paginator.Paginator.page_range") is now an iterator instead of a list. In versions of Django previous to 1.8, `Paginator.page_range` returned a `list` in Python 2 and a `range` in Python 3. Django 1.8 consistently returned a list, but an iterator is more efficient. Existing code that depends on `list` specific features, such as indexing, can be ported by converting the iterator into a `list` using `list()`. ### Implicit `QuerySet` `__in` lookup removed[¶](#implicit-queryset-in-lookup-removed "Link to this heading") In earlier versions, queries such as: ``` Model.objects.filter(related_id=RelatedModel.objects.all()) ``` would implicitly convert to: ``` Model.objects.filter(related_id__in=RelatedModel.objects.all()) ``` resulting in SQL like `"related_id IN (SELECT id FROM ...)"`. This implicit `__in` no longer happens so the “IN” SQL is now “=”, and if the subquery returns multiple results, at least some databases will throw an error. ### `contrib.admin` browser support[¶](#contrib-admin-browser-support "Link to this heading") The admin no longer supports Internet Explorer 8 and below, as these browsers have reached end-of-life. CSS and images to support Internet Explorer 6 and 7 have been removed. PNG and GIF icons have been replaced with SVG icons, which are not supported by Internet Explorer 8 and earlier. The jQuery library embedded in the admin has been upgraded from version 1.11.2 to 2.1.4. jQuery 2.x has the same API as jQuery 1.x, but does not support Internet Explorer 6, 7, or 8, allowing for better performance and a smaller file size. If you need to support IE8 and must also use the latest version of Django, you can override the admin’s copy of jQuery with your own by creating a Django application with this structure: ``` app/static/admin/js/vendor/ jquery.js jquery.min.js ``` ### `SyntaxError` when installing Django `setuptools` 5.5.x[¶](#syntaxerror-when-installing-django-setuptools-5-5-x "Link to this heading") When installing Django 1.9 or 1.9.1 with `setuptools` 5.5.x, you’ll see: ``` Compiling django/conf/app_template/apps.py ... File "django/conf/app_template/apps.py", line 4 class {{ camel_case_app_name }}Config(AppConfig): ^ SyntaxError: invalid syntax Compiling django/conf/app_template/models.py ... File "django/conf/app_template/models.py", line 1 {{ unicode_literals }}from django.db import models ^ SyntaxError: invalid syntax ``` It’s safe to ignore these errors (Django will still install just fine), but you can avoid them by upgrading `setuptools` to a more recent version. If you’re using pip, you can upgrade pip using `python -m pip install -U pip` which will also upgrade `setuptools`. This is resolved in later versions of Django as described in the [Django 1.9.2 release notes](../1.9.2/). ### Miscellaneous[¶](#miscellaneous "Link to this heading") * The jQuery static files in `contrib.admin` have been moved into a `vendor/jquery` subdirectory. * The text displayed for null columns in the admin changelist `list_display` cells has changed from `(None)` (or its translated equivalent) to `-` (a dash). * `django.http.responses.REASON_PHRASES` and `django.core.handlers.wsgi.STATUS_CODE_TEXT` have been removed. Use Python’s Standard Library instead: [`http.client.responses`](https://docs.python.org/3/library/http.client.html#http.client.responses "(in Python v3.15)") for Python 3 and [httplib.responses](https://docs.python.org/2/library/httplib.html#httplib.responses) for Python 2. * `ValuesQuerySet` and `ValuesListQuerySet` have been removed. * The `admin/base.html` template no longer sets `window.__admin_media_prefix__` or `window.__admin_utc_offset__`. Image references in JavaScript that used that value to construct absolute URLs have been moved to CSS for easier customization. The UTC offset is stored on a data attribute of the `` tag. * `CommaSeparatedIntegerField` validation has been refined to forbid values like `','`, `',1'`, and `'1,,2'`. * Form initialization was moved from the [`ProcessFormView.get()`](../../ref/class-based-views/mixins-editing/#django.views.generic.edit.ProcessFormView.get "django.views.generic.edit.ProcessFormView.get") method to the new [`FormMixin.get_context_data()`](../../ref/class-based-views/mixins-editing/#django.views.generic.edit.FormMixin.get_context_data "django.views.generic.edit.FormMixin.get_context_data") method. This may be backwards incompatible if you have overridden the `get_context_data()` method without calling `super()`. * Support for PostGIS 1.5 has been dropped. * The `django.contrib.sites.models.Site.domain` field was changed to be [`unique`](../../ref/models/fields/#django.db.models.Field.unique "django.db.models.Field.unique"). * In order to enforce test isolation, database queries are not allowed by default in [`SimpleTestCase`](../../topics/testing/tools/#django.test.SimpleTestCase "django.test.SimpleTestCase") tests anymore. You can disable this behavior by setting the `allow_database_queries` class attribute to `True` on your test class. * `ResolverMatch.app_name` was changed to contain the full namespace path in the case of nested namespaces. For consistency with `ResolverMatch.namespace`, the empty value is now an empty string instead of `None`. * For security hardening, session keys must be at least 8 characters. * Private function `django.utils.functional.total_ordering()` has been removed. It contained a workaround for a `functools.total_ordering()` bug in Python versions older than 2.7.3. * XML serialization (either through [`dumpdata`](../../ref/django-admin/#django-admin-dumpdata) or the syndication framework) used to output any characters it received. Now if the content to be serialized contains any control characters not allowed in the XML 1.0 standard, the serialization will fail with a [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)"). * [`CharField`](../../ref/forms/fields/#django.forms.CharField "django.forms.CharField") now strips input of leading and trailing whitespace by default. This can be disabled by setting the new [`strip`](../../ref/forms/fields/#django.forms.CharField.strip "django.forms.CharField.strip") argument to `False`. * Template text that is translated and uses two or more consecutive percent signs, e.g. `"%%"`, may have a new `msgid` after `makemessages` is run (most likely the translation will be marked fuzzy). The new `msgid` will be marked `"#, python-format"`. * If neither [`request.current_app`](../../ref/request-response/#django.http.HttpRequest.current_app "django.http.HttpRequest.current_app") nor [`Context.current_app`](../../ref/templates/api/#django.template.Context "django.template.Context") are set, the [`url`](../../ref/templates/builtins/#std-templatetag-url) template tag will now use the namespace of the current request. Set `request.current_app` to `None` if you don’t want to use a namespace hint. * The [`SILENCED_SYSTEM_CHECKS`](../../ref/settings/#std-setting-SILENCED_SYSTEM_CHECKS) setting now silences messages of all levels. Previously, messages of `ERROR` level or higher were printed to the console. * The `FlatPage.enable_comments` field is removed from the `FlatPageAdmin` as it’s unused by the application. If your project or a third-party app makes use of it, [create a custom ModelAdmin](../../ref/contrib/flatpages/#flatpages-admin) to add it back. * The return value of [`setup_databases()`](../../topics/testing/advanced/#django.test.runner.DiscoverRunner.setup_databases "django.test.runner.DiscoverRunner.setup_databases") and the first argument of [`teardown_databases()`](../../topics/testing/advanced/#django.test.runner.DiscoverRunner.teardown_databases "django.test.runner.DiscoverRunner.teardown_databases") changed. They used to be `(old_names, mirrors)` tuples. Now they’re just the first item, `old_names`. * By default [`LiveServerTestCase`](../../topics/testing/tools/#django.test.LiveServerTestCase "django.test.LiveServerTestCase") attempts to find an available port in the 8081-8179 range instead of just trying port 8081. * The system checks for [`ModelAdmin`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin "django.contrib.admin.ModelAdmin") now check instances rather than classes. * The private API to apply mixed migration plans has been dropped for performance reasons. Mixed plans consist of a list of migrations where some are being applied and others are being unapplied. * The related model object descriptor classes in `django.db.models.fields.related` (private API) are moved from the `related` module to `related_descriptors` and renamed as follows: * `ReverseSingleRelatedObjectDescriptor` is `ForwardManyToOneDescriptor` * `SingleRelatedObjectDescriptor` is `ReverseOneToOneDescriptor` * `ForeignRelatedObjectsDescriptor` is `ReverseManyToOneDescriptor` * `ManyRelatedObjectsDescriptor` is `ManyToManyDescriptor` * If you implement a custom [`handler404`](../../ref/urls/#django.conf.urls.handler404 "django.conf.urls.handler404") view, it must return a response with an HTTP 404 status code. Use [`HttpResponseNotFound`](../../ref/request-response/#django.http.HttpResponseNotFound "django.http.HttpResponseNotFound") or pass `status=404` to the [`HttpResponse`](../../ref/request-response/#django.http.HttpResponse "django.http.HttpResponse"). Otherwise, [`APPEND_SLASH`](../../ref/settings/#std-setting-APPEND_SLASH) won’t work correctly with `DEBUG=False`. ## Features deprecated in 1.9[¶](#features-deprecated-in-1-9 "Link to this heading") ### `assignment_tag()`[¶](#assignment-tag "Link to this heading") Django 1.4 added the `assignment_tag` helper to ease the creation of template tags that store results in a template variable. The [`simple_tag()`](../../howto/custom-template-tags/#django.template.Library.simple_tag "django.template.Library.simple_tag") helper has gained this same ability, making the `assignment_tag` obsolete. Tags that use `assignment_tag` should be updated to use `simple_tag`. ### `{% cycle %}` syntax with comma-separated arguments[¶](#cycle-syntax-with-comma-separated-arguments "Link to this heading") The [`cycle`](../../ref/templates/builtins/#std-templatetag-cycle) tag supports an inferior old syntax from previous Django versions: ``` {% cycle row1,row2,row3 %} ``` Its parsing caused bugs with the current syntax, so support for the old syntax will be removed in Django 1.10 following an accelerated deprecation. ### `ForeignKey` and `OneToOneField` `on_delete` argument[¶](#foreignkey-and-onetoonefield-on-delete-argument "Link to this heading") In order to increase awareness about cascading model deletion, the `on_delete` argument of `ForeignKey` and `OneToOneField` will be required in Django 2.0. Update models and existing migrations to explicitly set the argument. Since the default is `models.CASCADE`, add `on_delete=models.CASCADE` to all `ForeignKey` and `OneToOneField`s that don’t use a different option. You can also pass it as the second positional argument if you don’t care about compatibility with older versions of Django. ### `Field.rel` changes[¶](#field-rel-changes "Link to this heading") `Field.rel` and its methods and attributes have changed to match the related fields API. The `Field.rel` attribute is renamed to `remote_field` and many of its methods and attributes are either changed or renamed. The aim of these changes is to provide a documented API for relation fields. ### `GeoManager` and `GeoQuerySet` custom methods[¶](#geomanager-and-geoqueryset-custom-methods "Link to this heading") All custom `GeoQuerySet` methods (`area()`, `distance()`, `gml()`, …) have been replaced by equivalent geographic expressions in annotations (see in new features). Hence the need to set a custom `GeoManager` to GIS-enabled models is now obsolete. As soon as your code doesn’t call any of the deprecated methods, you can simply remove the `objects = GeoManager()` lines from your models. ### Template loader APIs have changed[¶](#template-loader-apis-have-changed "Link to this heading") Django template loaders have been updated to allow recursive template extending. This change necessitated a new template loader API. The old `load_template()` and `load_template_sources()` methods are now deprecated. Details about the new API can be found [in the template loader documentation](../../ref/templates/api/#custom-template-loaders). ### Passing a 3-tuple or an `app_name` to `include()`[¶](#passing-a-3-tuple-or-an-app-name-to-include "Link to this heading") The instance namespace part of passing a tuple as an argument to `include()` has been replaced by passing the `namespace` argument to `include()`. For example: ``` polls_patterns = [ url(...), ] urlpatterns = [ url(r"^polls/", include((polls_patterns, "polls", "author-polls"))), ] ``` becomes: ``` polls_patterns = ( [ url(...), ], "polls", ) # 'polls' is the app_name urlpatterns = [ url(r"^polls/", include(polls_patterns, namespace="author-polls")), ] ``` The `app_name` argument to `include()` has been replaced by passing a 2-tuple (as above), or passing an object or module with an `app_name` attribute (as below). If the `app_name` is set in this new way, the `namespace` argument is no longer required. It will default to the value of `app_name`. For example, the URL patterns in the tutorial are changed from: `mysite/urls.py`[¶](#id2 "Link to this code")** ``` urlpatterns = [url(r"^polls/", include("polls.urls", namespace="polls")), ...] ``` to: `mysite/urls.py`[¶](#id3 "Link to this code")** ``` urlpatterns = [ url(r"^polls/", include("polls.urls")), # 'namespace="polls"' removed ..., ] ``` `polls/urls.py`[¶](#id4 "Link to this code")** ``` app_name = "polls" # added urlpatterns = [...] ``` This change also means that the old way of including an `AdminSite` instance is deprecated. Instead, pass `admin.site.urls` directly to `django.conf.urls.url()`: `urls.py`[¶](#id5 "Link to this code")** ``` from django.conf.urls import url from django.contrib import admin urlpatterns = [ url(r"^admin/", admin.site.urls), ] ``` ### URL application namespace required if setting an instance namespace[¶](#url-application-namespace-required-if-setting-an-instance-namespace "Link to this heading") In the past, an instance namespace without an application namespace would serve the same purpose as the application namespace, but it was impossible to reverse the patterns if there was an application namespace with the same name. Includes that specify an instance namespace require that the included URLconf sets an application namespace. ### `current_app` parameter to `contrib.auth` views[¶](#current-app-parameter-to-contrib-auth-views "Link to this heading") All views in `django.contrib.auth.views` have the following structure: ``` def view(request, ..., current_app=None, ...): ... if current_app is not None: request.current_app = current_app return TemplateResponse(request, template_name, context) ``` As of Django 1.8, `current_app` is set on the `request` object. For consistency, these views will require the caller to set `current_app` on the `request` instead of passing it in a separate argument. ### `django.contrib.gis.geoip`[¶](#django-contrib-gis-geoip "Link to this heading") The [`django.contrib.gis.geoip2`](../../ref/contrib/gis/geoip2/#module-django.contrib.gis.geoip2 "django.contrib.gis.geoip2: Python interface for MaxMind's GeoIP2 databases.") module supersedes `django.contrib.gis.geoip`. The new module provides a similar API except that it doesn’t provide the legacy GeoIP-Python API compatibility methods. ### Miscellaneous[¶](#id1 "Link to this heading") * The `weak` argument to `django.dispatch.signals.Signal.disconnect()` has been deprecated as it has no effect. * The `check_aggregate_support()` method of `django.db.backends.base.BaseDatabaseOperations` has been deprecated and will be removed in Django 2.0. The more general `check_expression_support()` should be used instead. * `django.forms.extras` is deprecated. You can find [`SelectDateWidget`](../../ref/forms/widgets/#django.forms.SelectDateWidget "django.forms.SelectDateWidget") in `django.forms.widgets` (or simply `django.forms`) instead. * Private API `django.db.models.fields.add_lazy_relation()` is deprecated. * The `django.contrib.auth.tests.utils.skipIfCustomUser()` decorator is deprecated. With the test discovery changes in Django 1.6, the tests for `django.contrib` apps are no longer run as part of the user’s project. Therefore, the `@skipIfCustomUser` decorator is no longer needed to decorate tests in `django.contrib.auth`. * If you customized some [error handlers](../../ref/views/#error-views), the view signatures with only one request parameter are deprecated. The views should now also accept a second `exception` positional parameter. * The `django.utils.feedgenerator.Atom1Feed.mime_type` and `django.utils.feedgenerator.RssFeed.mime_type` attributes are deprecated in favor of `content_type`. * [`Signer`](../../topics/signing/#django.core.signing.Signer "django.core.signing.Signer") now issues a warning if an invalid separator is used. This will become an exception in Django 1.10. * `django.db.models.Field._get_val_from_obj()` is deprecated in favor of `Field.value_from_object()`. * `django.template.loaders.eggs.Loader` is deprecated as distributing applications as eggs is not recommended. * The `callable_obj` keyword argument to `SimpleTestCase.assertRaisesMessage()` is deprecated. Pass the callable as a positional argument instead. * The `allow_tags` attribute on methods of `ModelAdmin` has been deprecated. Use [`format_html()`](../../ref/utils/#django.utils.html.format_html "django.utils.html.format_html"), [`format_html_join()`](../../ref/utils/#django.utils.html.format_html_join "django.utils.html.format_html_join"), or [`mark_safe()`](../../ref/utils/#django.utils.safestring.mark_safe "django.utils.safestring.mark_safe") when constructing the method’s return value instead. * The `enclosure` keyword argument to `SyndicationFeed.add_item()` is deprecated. Use the new `enclosures` argument which accepts a list of `Enclosure` objects instead of a single one. * The `django.template.loader.LoaderOrigin` and `django.template.base.StringOrigin` aliases for `django.template.base.Origin` are deprecated. ## Features removed in 1.9[¶](#features-removed-in-1-9 "Link to this heading") These features have reached the end of their deprecation cycle and are removed in Django 1.9. See [Features deprecated in 1.7](../1.7/#deprecated-features-1-7) for details, including how to remove usage of these features. * `django.utils.dictconfig` is removed. * `django.utils.importlib` is removed. * `django.utils.tzinfo` is removed. * `django.utils.unittest` is removed. * The `syncdb` command is removed. * `django.db.models.signals.pre_syncdb` and `django.db.models.signals.post_syncdb` is removed. * Support for `allow_syncdb` on database routers is removed. * Automatic syncing of apps without migrations is removed. Migrations are compulsory for all apps unless you pass the [`migrate --run-syncdb`](../../ref/django-admin/#cmdoption-migrate-run-syncdb) option. * The SQL management commands for apps without migrations, `sql`, `sqlall`, `sqlclear`, `sqldropindexes`, and `sqlindexes`, are removed. * Support for automatic loading of `initial_data` fixtures and initial SQL data is removed. * All models need to be defined inside an installed application or declare an explicit [`app_label`](../../ref/models/options/#django.db.models.Options.app_label "django.db.models.Options.app_label"). Furthermore, it isn’t possible to import them before their application is loaded. In particular, it isn’t possible to import models inside the root package of an application. * The model and form `IPAddressField` is removed. A stub field remains for compatibility with historical migrations. * `AppCommand.handle_app()` is no longer supported. * `RequestSite` and `get_current_site()` are no longer importable from `django.contrib.sites.models`. * FastCGI support via the `runfcgi` management command is removed. * `django.utils.datastructures.SortedDict` is removed. * `ModelAdmin.declared_fieldsets` is removed. * The `util` modules that provided backwards compatibility are removed: * `django.contrib.admin.util` * `django.contrib.gis.db.backends.util` * `django.db.backends.util` * `django.forms.util` * `ModelAdmin.get_formsets` is removed. * The backward compatible shims introduced to rename the `BaseMemcachedCache._get_memcache_timeout()` method to `get_backend_timeout()` is removed. * The `--natural` and `-n` options for [`dumpdata`](../../ref/django-admin/#django-admin-dumpdata) are removed. * The `use_natural_keys` argument for `serializers.serialize()` is removed. * Private API `django.forms.forms.get_declared_fields()` is removed. * The ability to use a `SplitDateTimeWidget` with `DateTimeField` is removed. * The `WSGIRequest.REQUEST` property is removed. * The class `django.utils.datastructures.MergeDict` is removed. * The `zh-cn` and `zh-tw` language codes are removed. * The internal `django.utils.functional.memoize()` is removed. * `django.core.cache.get_cache` is removed. * `django.db.models.loading` is removed. * Passing callable arguments to querysets is no longer possible. * `BaseCommand.requires_model_validation` is removed in favor of `requires_system_checks`. Admin validators is replaced by admin checks. * The `ModelAdmin.validator_class` and `default_validator_class` attributes are removed. * `ModelAdmin.validate()` is removed. * `django.db.backends.DatabaseValidation.validate_field` is removed in favor of the `check_field` method. * The `validate` management command is removed. * `django.utils.module_loading.import_by_path` is removed in favor of `django.utils.module_loading.import_string`. * `ssi` and `url` template tags are removed from the `future` template tag library. * `django.utils.text.javascript_quote()` is removed. * Database test settings as independent entries in the database settings, prefixed by `TEST_`, are no longer supported. * The `cache_choices` option to [`ModelChoiceField`](../../ref/forms/fields/#django.forms.ModelChoiceField "django.forms.ModelChoiceField") and [`ModelMultipleChoiceField`](../../ref/forms/fields/#django.forms.ModelMultipleChoiceField "django.forms.ModelMultipleChoiceField") is removed. * The default value of the [`RedirectView.permanent`](../../ref/class-based-views/base/#django.views.generic.base.RedirectView.permanent "django.views.generic.base.RedirectView.permanent") attribute has changed from `True` to `False`. * `django.contrib.sitemaps.FlatPageSitemap` is removed in favor of `django.contrib.flatpages.sitemaps.FlatPageSitemap`. * Private API `django.test.utils.TestTemplateLoader` is removed. * The `django.contrib.contenttypes.generic` module is removed. [**Back to Top](#top) ## Additional Information ### Support Django! * [Paul McLanahan donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.9 release notes](#) * [Python compatibility](#python-compatibility) * [What’s new in Django 1.9](#what-s-new-in-django-1-9) * [Performing actions after a transaction commit](#performing-actions-after-a-transaction-commit) * [Password validation](#password-validation) * [Permission mixins for class-based views](#permission-mixins-for-class-based-views) * [New styling for `contrib.admin`](#new-styling-for-contrib-admin) * [Running tests in parallel](#running-tests-in-parallel) * [Minor features](#minor-features) * [`django.contrib.admin`](#django-contrib-admin) * [`django.contrib.admindocs`](#django-contrib-admindocs) * [`django.contrib.auth`](#django-contrib-auth) * [`django.contrib.contenttypes`](#django-contrib-contenttypes) * [`django.contrib.gis`](#django-contrib-gis) * [`django.contrib.postgres`](#django-contrib-postgres) * [`django.contrib.sessions`](#django-contrib-sessions) * [`django.contrib.sites`](#django-contrib-sites) * [`django.contrib.syndication`](#django-contrib-syndication) * [Cache](#cache) * [CSRF](#csrf) * [Database backends](#database-backends) * [File Storage](#file-storage) * [Forms](#forms) * [Generic Views](#generic-views) * [Internationalization](#internationalization) * [Management Commands](#management-commands) * [Migrations](#migrations) * [Models](#models) * [Requests and Responses](#requests-and-responses) * [Templates](#templates) * [Tests](#tests) * [URLs](#urls) * [Validators](#validators) * [Backwards incompatible changes in 1.9](#backwards-incompatible-changes-in-1-9) * [Database backend API](#database-backend-api) * [Default settings that were tuples are now lists](#default-settings-that-were-tuples-are-now-lists) * [`is_usable` attribute on template loaders is removed](#is-usable-attribute-on-template-loaders-is-removed) * [Related set direct assignment](#related-set-direct-assignment) * [Filesystem-based template loaders catch more specific exceptions](#filesystem-based-template-loaders-catch-more-specific-exceptions) * [HTTP redirects no longer forced to absolute URIs](#http-redirects-no-longer-forced-to-absolute-uris) * [Dropped support for PostgreSQL 9.0](#dropped-support-for-postgresql-9-0) * [Dropped support for Oracle 11.1](#dropped-support-for-oracle-11-1) * [Bulk behavior of `add()` method of related managers](#bulk-behavior-of-add-method-of-related-managers) * [Template `LoaderOrigin` and `StringOrigin` are removed](#template-loaderorigin-and-stringorigin-are-removed) * [Changes to the default logging configuration](#changes-to-the-default-logging-configuration) * [`HttpRequest` details in error reporting](#httprequest-details-in-error-reporting) * [Removal of time zone aware global adapters and converters for datetimes](#removal-of-time-zone-aware-global-adapters-and-converters-for-datetimes) * [Template tag modules are imported when templates are configured](#template-tag-modules-are-imported-when-templates-are-configured) * [`django.template.base.add_to_builtins()` is removed](#django-template-base-add-to-builtins-is-removed) * [`simple_tag` now wraps tag output in `conditional_escape`](#simple-tag-now-wraps-tag-output-in-conditional-escape) * [`Paginator.page_range`](#paginator-page-range) * [Implicit `QuerySet` `__in` lookup removed](#implicit-queryset-in-lookup-removed) * [`contrib.admin` browser support](#contrib-admin-browser-support) * [`SyntaxError` when installing Django `setuptools` 5.5.x](#syntaxerror-when-installing-django-setuptools-5-5-x) * [Miscellaneous](#miscellaneous) * [Features deprecated in 1.9](#features-deprecated-in-1-9) * [`assignment_tag()`](#assignment-tag) * [`{% cycle %}` syntax with comma-separated arguments](#cycle-syntax-with-comma-separated-arguments) * [`ForeignKey` and `OneToOneField` `on_delete` argument](#foreignkey-and-onetoonefield-on-delete-argument) * [`Field.rel` changes](#field-rel-changes) * [`GeoManager` and `GeoQuerySet` custom methods](#geomanager-and-geoqueryset-custom-methods) * [Template loader APIs have changed](#template-loader-apis-have-changed) * [Passing a 3-tuple or an `app_name` to `include()`](#passing-a-3-tuple-or-an-app-name-to-include) * [URL application namespace required if setting an instance namespace](#url-application-namespace-required-if-setting-an-instance-namespace) * [`current_app` parameter to `contrib.auth` views](#current-app-parameter-to-contrib-auth-views) * [`django.contrib.gis.geoip`](#django-contrib-gis-geoip) * [Miscellaneous](#id1) * [Features removed in 1.9](#features-removed-in-1-9) ---- url: https://docs.djangoproject.com/en/6.1/releases/3.0/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/3.0/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/3.0/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/3.0/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/3.0/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/3.0/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/3.0/) - [it](https://docs.djangoproject.com/it/6.1/releases/3.0/) - [id](https://docs.djangoproject.com/id/6.1/releases/3.0/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/3.0/) - [es](https://docs.djangoproject.com/es/6.1/releases/3.0/) - [el](https://docs.djangoproject.com/el/6.1/releases/3.0/) * * [dev](https://docs.djangoproject.com/en/dev/releases/3.0/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/3.0/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/3.0/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/3.0/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/3.0/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/3.0/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/3.0/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/3.0/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/3.0/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/3.0/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/3.0/) - [**](#top) # Django 3.0 release notes[¶](#django-3-0-release-notes "Link to this heading") *December 2, 2019* Welcome to Django 3.0! These release notes cover the [new features](#whats-new-3-0), as well as some [backwards incompatible changes](#backwards-incompatible-3-0) you’ll want to be aware of when upgrading from Django 2.2 or earlier. We’ve [dropped some features](#removed-features-3-0) that have reached the end of their deprecation cycle, and we’ve [begun the deprecation process for some features](#deprecated-features-3-0). See the [How to upgrade Django to a newer version](../../howto/upgrade-version/) guide if you’re updating an existing project. ## Python compatibility[¶](#python-compatibility "Link to this heading") Django 3.0 supports Python 3.6, 3.7, 3.8, and 3.9 (as of 3.0.11). We **highly recommend** and only officially support the latest release of each series. The Django 2.2.x series is the last to support Python 3.5. ## Third-party library support for older version of Django[¶](#third-party-library-support-for-older-version-of-django "Link to this heading") Following the release of Django 3.0, we suggest that third-party app authors drop support for all versions of Django prior to 2.2. At that time, you should be able to run your package’s tests using `python -Wd` so that deprecation warnings appear. After making the deprecation warning fixes, your app should be compatible with Django 3.0. ## What’s new in Django 3.0[¶](#what-s-new-in-django-3-0 "Link to this heading") ### MariaDB support[¶](#mariadb-support "Link to this heading") Django now officially supports [MariaDB](https://mariadb.org/) 10.1 and higher. See [MariaDB notes](../../ref/databases/#mariadb-notes) for more details. ### ASGI support[¶](#asgi-support "Link to this heading") Django 3.0 begins our journey to making Django fully async-capable by providing support for running as an [ASGI](https://asgi.readthedocs.io/) application. This is in addition to our existing WSGI support. Django intends to support both for the foreseeable future. Async features will only be available to applications that run under ASGI, however. At this stage async support only applies to the outer ASGI application. Internally everything remains synchronous. Asynchronous middleware, views, etc. are not yet supported. You can, however, use ASGI middleware around Django’s application, allowing you to combine Django with other ASGI frameworks. There is no need to switch your applications over unless you want to start experimenting with asynchronous code, but we have [documentation on deploying with ASGI](../../howto/deployment/asgi/) if you want to learn more. Note that as a side-effect of this change, Django is now aware of asynchronous event loops and will block you calling code marked as “async unsafe” - such as ORM operations - from an asynchronous context. If you were using Django from async code before, this may trigger if you were doing it incorrectly. If you see a `SynchronousOnlyOperation` error, then closely examine your code and move any database operations to be in a synchronous child thread. ### Exclusion constraints on PostgreSQL[¶](#exclusion-constraints-on-postgresql "Link to this heading") The new [`ExclusionConstraint`](../../ref/contrib/postgres/constraints/#django.contrib.postgres.constraints.ExclusionConstraint "django.contrib.postgres.constraints.ExclusionConstraint") class enable adding exclusion constraints on PostgreSQL. Constraints are added to models using the [`Meta.constraints`](../../ref/models/options/#django.db.models.Options.constraints "django.db.models.Options.constraints") option. ### Filter expressions[¶](#filter-expressions "Link to this heading") Expressions that output [`BooleanField`](../../ref/models/fields/#django.db.models.BooleanField "django.db.models.BooleanField") may now be used directly in `QuerySet` filters, without having to first annotate and then filter against the annotation. ### Enumerations for model field choices[¶](#enumerations-for-model-field-choices "Link to this heading") Custom enumeration types `TextChoices`, `IntegerChoices`, and `Choices` are now available as a way to define [`Field.choices`](../../ref/models/fields/#django.db.models.Field.choices "django.db.models.Field.choices"). `TextChoices` and `IntegerChoices` types are provided for text and integer fields. The `Choices` class allows defining a compatible enumeration for other concrete data types. These custom enumeration types support human-readable labels that can be translated and accessed via a property on the enumeration or its members. See [Enumeration types](../../ref/models/fields/#field-choices-enum-types) for more details and examples. ### Minor features[¶](#minor-features "Link to this heading") #### [`django.contrib.admin`](../../ref/contrib/admin/#module-django.contrib.admin "django.contrib.admin: Django's admin site.")[¶](#django-contrib-admin "Link to this heading") * Added support for the `admin_order_field` attribute on properties in [`ModelAdmin.list_display`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.list_display "django.contrib.admin.ModelAdmin.list_display"). * The new [`ModelAdmin.get_inlines()`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.get_inlines "django.contrib.admin.ModelAdmin.get_inlines") method allows specifying the inlines based on the request or model instance. * Select2 library is upgraded from version 4.0.3 to 4.0.7. * jQuery is upgraded from version 3.3.1 to 3.4.1. #### [`django.contrib.auth`](../../topics/auth/#module-django.contrib.auth "django.contrib.auth: Django's authentication framework.")[¶](#django-contrib-auth "Link to this heading") * The new `reset_url_token` attribute in [`PasswordResetConfirmView`](../../topics/auth/default/#django.contrib.auth.views.PasswordResetConfirmView "django.contrib.auth.views.PasswordResetConfirmView") allows specifying a token parameter displayed as a component of password reset URLs. * Added [`BaseBackend`](../../ref/contrib/auth/#django.contrib.auth.backends.BaseBackend "django.contrib.auth.backends.BaseBackend") class to ease customization of authentication backends. * Added [`get_user_permissions()`](../../ref/contrib/auth/#django.contrib.auth.models.User.get_user_permissions "django.contrib.auth.models.User.get_user_permissions") method to mirror the existing [`get_group_permissions()`](../../ref/contrib/auth/#django.contrib.auth.models.User.get_group_permissions "django.contrib.auth.models.User.get_group_permissions") method. * Added HTML `autocomplete` attribute to widgets of username, email, and password fields in [`django.contrib.auth.forms`](../../topics/auth/default/#module-django.contrib.auth.forms "django.contrib.auth.forms") for better interaction with browser password managers. * [`createsuperuser`](../../ref/django-admin/#django-admin-createsuperuser) now falls back to environment variables for password and required fields, when a corresponding command line argument isn’t provided in non-interactive mode. * [`REQUIRED_FIELDS`](../../topics/auth/customizing/#django.contrib.auth.models.CustomUser.REQUIRED_FIELDS "django.contrib.auth.models.CustomUser.REQUIRED_FIELDS") now supports [`ManyToManyField`](../../ref/models/fields/#django.db.models.ManyToManyField "django.db.models.ManyToManyField")s. * The new [`UserManager.with_perm()`](../../ref/contrib/auth/#django.contrib.auth.models.UserManager.with_perm "django.contrib.auth.models.UserManager.with_perm") method returns users that have the specified permission. * The default iteration count for the PBKDF2 password hasher is increased from 150,000 to 180,000. #### [`django.contrib.gis`](../../ref/contrib/gis/#module-django.contrib.gis "django.contrib.gis: Geographic Information System (GIS) extensions for Django")[¶](#django-contrib-gis "Link to this heading") * Allowed MySQL spatial lookup functions to operate on real geometries. Previous support was limited to bounding boxes. * Added the [`GeometryDistance`](../../ref/contrib/gis/functions/#django.contrib.gis.db.models.functions.GeometryDistance "django.contrib.gis.db.models.functions.GeometryDistance") function, supported on PostGIS. * Added support for the `furlong` unit in [`Distance`](../../ref/contrib/gis/measure/#django.contrib.gis.measure.Distance "django.contrib.gis.measure.Distance"). * The [`GEOIP_PATH`](../../ref/contrib/gis/geoip2/#std-setting-GEOIP_PATH) setting now supports [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)"). * The [`GeoIP2`](../../ref/contrib/gis/geoip2/#django.contrib.gis.geoip2.GeoIP2 "django.contrib.gis.geoip2.GeoIP2") class now accepts [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") `path`. #### [`django.contrib.postgres`](../../ref/contrib/postgres/#module-django.contrib.postgres "django.contrib.postgres: PostgreSQL-specific fields and features")[¶](#django-contrib-postgres "Link to this heading") * The new [`RangeOperators`](../../ref/contrib/postgres/fields/#django.contrib.postgres.fields.RangeOperators "django.contrib.postgres.fields.RangeOperators") helps to avoid typos in SQL operators that can be used together with [`RangeField`](../../ref/contrib/postgres/fields/#django.contrib.postgres.fields.RangeField "django.contrib.postgres.fields.RangeField"). * The new [`RangeBoundary`](../../ref/contrib/postgres/fields/#django.contrib.postgres.fields.RangeBoundary "django.contrib.postgres.fields.RangeBoundary") expression represents the range boundaries. * The new [`AddIndexConcurrently`](../../ref/contrib/postgres/operations/#django.contrib.postgres.operations.AddIndexConcurrently "django.contrib.postgres.operations.AddIndexConcurrently") and [`RemoveIndexConcurrently`](../../ref/contrib/postgres/operations/#django.contrib.postgres.operations.RemoveIndexConcurrently "django.contrib.postgres.operations.RemoveIndexConcurrently") classes allow creating and dropping indexes `CONCURRENTLY` on PostgreSQL. #### [`django.contrib.sessions`](../../topics/http/sessions/#module-django.contrib.sessions "django.contrib.sessions: Provides session management for Django projects.")[¶](#django-contrib-sessions "Link to this heading") * The new [`get_session_cookie_age()`](../../topics/http/sessions/#django.contrib.sessions.backends.base.SessionBase.get_session_cookie_age "django.contrib.sessions.backends.base.SessionBase.get_session_cookie_age") method allows dynamically specifying the session cookie age. #### [`django.contrib.syndication`](../../ref/contrib/syndication/#module-django.contrib.syndication "django.contrib.syndication: A framework for generating syndication feeds, in RSS and Atom, quite easily.")[¶](#django-contrib-syndication "Link to this heading") * Added the `language` class attribute to the [`django.contrib.syndication.views.Feed`](../../ref/contrib/syndication/#django.contrib.syndication.views.Feed "django.contrib.syndication.views.Feed") to customize a feed language. The default value is [`get_language()`](../../ref/utils/#django.utils.translation.get_language "django.utils.translation.get_language") instead of [`LANGUAGE_CODE`](../../ref/settings/#std-setting-LANGUAGE_CODE). #### Cache[¶](#cache "Link to this heading") * [`add_never_cache_headers()`](../../ref/utils/#django.utils.cache.add_never_cache_headers "django.utils.cache.add_never_cache_headers") and [`never_cache()`](../../topics/http/decorators/#django.views.decorators.cache.never_cache "django.views.decorators.cache.never_cache") now add the `private` directive to `Cache-Control` headers. #### File Storage[¶](#file-storage "Link to this heading") * The new [`Storage.get_alternative_name()`](../../ref/files/storage/#django.core.files.storage.Storage.get_alternative_name "django.core.files.storage.Storage.get_alternative_name") method allows customizing the algorithm for generating filenames if a file with the uploaded name already exists. #### Forms[¶](#forms "Link to this heading") * Formsets may control the widget used when ordering forms via [`can_order`](../../topics/forms/formsets/#django.forms.formsets.BaseFormSet.can_order "django.forms.formsets.BaseFormSet.can_order") by setting the [`ordering_widget`](../../topics/forms/formsets/#django.forms.formsets.BaseFormSet.ordering_widget "django.forms.formsets.BaseFormSet.ordering_widget") attribute or overriding [`get_ordering_widget`](../../topics/forms/formsets/#django.forms.formsets.BaseFormSet.get_ordering_widget "django.forms.formsets.BaseFormSet.get_ordering_widget"). #### Internationalization[¶](#internationalization "Link to this heading") * Added the [`LANGUAGE_COOKIE_HTTPONLY`](../../ref/settings/#std-setting-LANGUAGE_COOKIE_HTTPONLY), [`LANGUAGE_COOKIE_SAMESITE`](../../ref/settings/#std-setting-LANGUAGE_COOKIE_SAMESITE), and [`LANGUAGE_COOKIE_SECURE`](../../ref/settings/#std-setting-LANGUAGE_COOKIE_SECURE) settings to set the `HttpOnly`, `SameSite`, and `Secure` flags on language cookies. The default values of these settings preserve the previous behavior. * Added support and translations for the Uzbek language. #### Logging[¶](#logging "Link to this heading") * The new `reporter_class` parameter of [`AdminEmailHandler`](../../ref/logging/#django.utils.log.AdminEmailHandler "django.utils.log.AdminEmailHandler") allows providing an `django.views.debug.ExceptionReporter` subclass to customize the traceback text sent to site [`ADMINS`](../../ref/settings/#std-setting-ADMINS) when [`DEBUG`](../../ref/settings/#std-setting-DEBUG) is `False`. #### Management Commands[¶](#management-commands "Link to this heading") * The new [`compilemessages --ignore`](../../ref/django-admin/#cmdoption-compilemessages-ignore) option allows ignoring specific directories when searching for `.po` files to compile. * [`showmigrations --list`](../../ref/django-admin/#cmdoption-showmigrations-list) now shows the applied datetimes when `--verbosity` is 2 and above. * On PostgreSQL, [`dbshell`](../../ref/django-admin/#django-admin-dbshell) now supports client-side TLS certificates. * [`inspectdb`](../../ref/django-admin/#django-admin-inspectdb) now introspects [`OneToOneField`](../../ref/models/fields/#django.db.models.OneToOneField "django.db.models.OneToOneField") when a foreign key has a unique or primary key constraint. * The new [`--skip-checks`](../../ref/django-admin/#cmdoption-skip-checks) option skips running system checks prior to running the command. * The [`startapp --template`](../../ref/django-admin/#cmdoption-startapp-template) and [`startproject --template`](../../ref/django-admin/#cmdoption-startproject-template) options now support templates stored in XZ archives (`.tar.xz`, `.txz`) and LZMA archives (`.tar.lzma`, `.tlz`). #### Models[¶](#models "Link to this heading") * Added hash database functions [`MD5`](../../ref/models/database-functions/#django.db.models.functions.MD5 "django.db.models.functions.MD5"), [`SHA1`](../../ref/models/database-functions/#django.db.models.functions.SHA1 "django.db.models.functions.SHA1"), [`SHA224`](../../ref/models/database-functions/#django.db.models.functions.SHA224 "django.db.models.functions.SHA224"), [`SHA256`](../../ref/models/database-functions/#django.db.models.functions.SHA256 "django.db.models.functions.SHA256"), [`SHA384`](../../ref/models/database-functions/#django.db.models.functions.SHA384 "django.db.models.functions.SHA384"), and [`SHA512`](../../ref/models/database-functions/#django.db.models.functions.SHA512 "django.db.models.functions.SHA512"). * Added the [`Sign`](../../ref/models/database-functions/#django.db.models.functions.Sign "django.db.models.functions.Sign") database function. * The new `is_dst` parameter of the [`Trunc`](../../ref/models/database-functions/#django.db.models.functions.Trunc "django.db.models.functions.Trunc") database functions determines the treatment of nonexistent and ambiguous datetimes. * `connection.queries` now shows `COPY … TO` statements on PostgreSQL. * [`FilePathField`](../../ref/models/fields/#django.db.models.FilePathField "django.db.models.FilePathField") now accepts a callable for `path`. * Allowed symmetrical intermediate table for self-referential [`ManyToManyField`](../../ref/models/fields/#django.db.models.ManyToManyField "django.db.models.ManyToManyField"). * The `name` attributes of [`CheckConstraint`](../../ref/models/constraints/#django.db.models.CheckConstraint "django.db.models.CheckConstraint"), [`UniqueConstraint`](../../ref/models/constraints/#django.db.models.UniqueConstraint "django.db.models.UniqueConstraint"), and [`Index`](../../ref/models/indexes/#django.db.models.Index "django.db.models.Index") now support app label and class interpolation using the `'%(app_label)s'` and `'%(class)s'` placeholders. * The new [`Field.descriptor_class`](../../ref/models/fields/#django.db.models.Field.descriptor_class "django.db.models.Field.descriptor_class") attribute allows model fields to customize the get and set behavior by overriding their [descriptors](https://docs.python.org/3/reference/datamodel.html#descriptors "(in Python v3.15)"). * [`Avg`](../../ref/models/querysets/#django.db.models.Avg "django.db.models.Avg") and [`Sum`](../../ref/models/querysets/#django.db.models.Sum "django.db.models.Sum") now support the `distinct` argument. * Added [`SmallAutoField`](../../ref/models/fields/#django.db.models.SmallAutoField "django.db.models.SmallAutoField") which acts much like an [`AutoField`](../../ref/models/fields/#django.db.models.AutoField "django.db.models.AutoField") except that it only allows values under a certain (database-dependent) limit. Values from `1` to `32767` are safe in all databases supported by Django. * [`AutoField`](../../ref/models/fields/#django.db.models.AutoField "django.db.models.AutoField"), [`BigAutoField`](../../ref/models/fields/#django.db.models.BigAutoField "django.db.models.BigAutoField"), and [`SmallAutoField`](../../ref/models/fields/#django.db.models.SmallAutoField "django.db.models.SmallAutoField") now inherit from `IntegerField`, `BigIntegerField` and `SmallIntegerField` respectively. System checks and validators are now also properly inherited. * [`FileField.upload_to`](../../ref/models/fields/#django.db.models.FileField.upload_to "django.db.models.FileField.upload_to") now supports [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)"). * [`CheckConstraint`](../../ref/models/constraints/#django.db.models.CheckConstraint "django.db.models.CheckConstraint") is now supported on MySQL 8.0.16+. * The new `allows_group_by_selected_pks_on_model()` method of `django.db.backends.base.BaseDatabaseFeatures` allows optimization of `GROUP BY` clauses to require only the selected models’ primary keys. By default, it’s supported only for managed models on PostgreSQL. To enable the `GROUP BY` primary key-only optimization for unmanaged models, you have to subclass the PostgreSQL database engine, overriding the features class `allows_group_by_selected_pks_on_model()` method as you require. See [Subclassing the built-in database backends](../../ref/databases/#subclassing-database-backends) for an example. #### Requests and Responses[¶](#requests-and-responses "Link to this heading") * Allowed [`HttpResponse`](../../ref/request-response/#django.http.HttpResponse "django.http.HttpResponse") to be initialized with [`memoryview`](https://docs.python.org/3/builtins/stdtypes.html#memoryview "(in Python v3.15)") content. * For use in, for example, Django templates, [`HttpRequest.headers`](../../ref/request-response/#django.http.HttpRequest.headers "django.http.HttpRequest.headers") now allows lookups using underscores (e.g. `user_agent`) in place of hyphens. #### Security[¶](#security "Link to this heading") * [`X_FRAME_OPTIONS`](../../ref/settings/#std-setting-X_FRAME_OPTIONS) now defaults to `'DENY'`. In older versions, the [`X_FRAME_OPTIONS`](../../ref/settings/#std-setting-X_FRAME_OPTIONS) setting defaults to `'SAMEORIGIN'`. If your site uses frames of itself, you will need to explicitly set `X_FRAME_OPTIONS = 'SAMEORIGIN'` for them to continue working. * [`SECURE_CONTENT_TYPE_NOSNIFF`](../../ref/settings/#std-setting-SECURE_CONTENT_TYPE_NOSNIFF) now defaults to `True`. With this enabled, [`SecurityMiddleware`](../../ref/middleware/#django.middleware.security.SecurityMiddleware "django.middleware.security.SecurityMiddleware") sets the [X-Content-Type-Options: nosniff](../../ref/middleware/#x-content-type-options) header on all responses that do not already have it. * [`SecurityMiddleware`](../../ref/middleware/#django.middleware.security.SecurityMiddleware "django.middleware.security.SecurityMiddleware") can now send the [Referrer-Policy](../../ref/middleware/#referrer-policy) header. #### Tests[¶](#tests "Link to this heading") * The new test [`Client`](../../topics/testing/tools/#django.test.Client "django.test.Client") argument `raise_request_exception` allows controlling whether or not exceptions raised during the request should also be raised in the test. The value defaults to `True` for backwards compatibility. If it is `False` and an exception occurs, the test client will return a 500 response with the attribute [`exc_info`](../../topics/testing/tools/#django.test.Response.exc_info "django.test.Response.exc_info"), a tuple providing information of the exception that occurred. * Tests and test cases to run can be selected by test name pattern using the new [`test -k`](../../ref/django-admin/#cmdoption-test-k) option. * HTML comparison, as used by [`assertHTMLEqual()`](../../topics/testing/tools/#django.test.SimpleTestCase.assertHTMLEqual "django.test.SimpleTestCase.assertHTMLEqual"), now treats text, character references, and entity references that refer to the same character as equivalent. * [`DiscoverRunner`](../../topics/testing/advanced/#django.test.runner.DiscoverRunner "django.test.runner.DiscoverRunner") can now spawn a debugger at each error or failure using the [`test --pdb`](../../ref/django-admin/#cmdoption-test-pdb) option. ## Backwards incompatible changes in 3.0[¶](#backwards-incompatible-changes-in-3-0 "Link to this heading") ### `Model.save()` when providing a default for the primary key[¶](#model-save-when-providing-a-default-for-the-primary-key "Link to this heading") [`Model.save()`](../../ref/models/instances/#django.db.models.Model.save "django.db.models.Model.save") no longer attempts to find a row when saving a new `Model` instance and a default value for the primary key is provided, and always performs a single `INSERT` query. In older Django versions, `Model.save()` performed either an `INSERT` or an `UPDATE` based on whether or not the row exists. This makes calling `Model.save()` while providing a default primary key value equivalent to passing [force\_insert=True](../../ref/models/instances/#ref-models-force-insert) to model’s `save()`. Attempts to use a new `Model` instance to update an existing row will result in an `IntegrityError`. In order to update an existing model for a specific primary key value, use the [`update_or_create()`](../../ref/models/querysets/#django.db.models.query.QuerySet.update_or_create "django.db.models.query.QuerySet.update_or_create") method or `QuerySet.filter(pk=…).update(…)` instead. For example: ``` >>> MyModel.objects.update_or_create(pk=existing_pk, defaults={"name": "new name"}) >>> MyModel.objects.filter(pk=existing_pk).update(name="new name") ``` ### Database backend API[¶](#database-backend-api "Link to this heading") This section describes changes that may be needed in third-party database backends. * The second argument of `DatabaseIntrospection.get_geometry_type()` is now the row description instead of the column name. * `DatabaseIntrospection.get_field_type()` may no longer return tuples. * If the database can create foreign keys in the same SQL statement that adds a field, add `SchemaEditor.sql_create_column_inline_fk` with the appropriate SQL; otherwise, set `DatabaseFeatures.can_create_inline_fk = False`. * `DatabaseFeatures.can_return_id_from_insert` and `can_return_ids_from_bulk_insert` are renamed to `can_return_columns_from_insert` and `can_return_rows_from_bulk_insert`. * Database functions now handle [`datetime.timezone`](https://docs.python.org/3/library/datetime.html#datetime.timezone "(in Python v3.15)") formats when created using [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)") instances (e.g. `timezone(timedelta(hours=5))`, which would output `'UTC+05:00'`). Third-party backends should handle this format when preparing [`DateTimeField`](../../ref/models/fields/#django.db.models.DateTimeField "django.db.models.DateTimeField") in `datetime_cast_date_sql()`, `datetime_extract_sql()`, etc. * Entries for `AutoField`, `BigAutoField`, and `SmallAutoField` are added to `DatabaseOperations.integer_field_ranges` to support the integer range validators on these field types. Third-party backends may need to customize the default entries. * `DatabaseOperations.fetch_returned_insert_id()` is replaced by `fetch_returned_insert_columns()` which returns a list of values returned by the `INSERT … RETURNING` statement, instead of a single value. * `DatabaseOperations.return_insert_id()` is replaced by `return_insert_columns()` that accepts a `fields` argument, which is an iterable of fields to be returned after insert. Usually this is only the auto-generated primary key. ### [`django.contrib.admin`](../../ref/contrib/admin/#module-django.contrib.admin "django.contrib.admin: Django's admin site.")[¶](#id1 "Link to this heading") * Admin’s model history change messages now prefers more readable field labels instead of field names. ### [`django.contrib.gis`](../../ref/contrib/gis/#module-django.contrib.gis "django.contrib.gis: Geographic Information System (GIS) extensions for Django")[¶](#id2 "Link to this heading") * Support for PostGIS 2.1 is removed. * Support for SpatiaLite 4.1 and 4.2 is removed. * Support for GDAL 1.11 and GEOS 3.4 is removed. ### Dropped support for PostgreSQL 9.4[¶](#dropped-support-for-postgresql-9-4 "Link to this heading") Upstream support for PostgreSQL 9.4 ends in December 2019. Django 3.0 supports PostgreSQL 9.5 and higher. ### Dropped support for Oracle 12.1[¶](#dropped-support-for-oracle-12-1 "Link to this heading") Upstream support for Oracle 12.1 ends in July 2021. Django 2.2 will be supported until April 2022. Django 3.0 officially supports Oracle 12.2 and 18c. ### Removed private Python 2 compatibility APIs[¶](#removed-private-python-2-compatibility-apis "Link to this heading") While Python 2 support was removed in Django 2.0, some private APIs weren’t removed from Django so that third party apps could continue using them until the Python 2 end-of-life. Since we expect apps to drop Python 2 compatibility when adding support for Django 3.0, we’re removing these APIs at this time. * `django.test.utils.str_prefix()` - Strings don’t have ‘u’ prefixes in Python 3. * `django.test.utils.patch_logger()` - Use [`unittest.TestCase.assertLogs()`](https://docs.python.org/3/library/unittest.html#unittest.TestCase.assertLogs "(in Python v3.15)") instead. * `django.utils.lru_cache.lru_cache()` - Alias of [`functools.lru_cache()`](https://docs.python.org/3/library/functools.html#functools.lru_cache "(in Python v3.15)"). * `django.utils.decorators.available_attrs()` - This function returns `functools.WRAPPER_ASSIGNMENTS`. * `django.utils.decorators.ContextDecorator` - Alias of [`contextlib.ContextDecorator`](https://docs.python.org/3/library/contextlib.html#contextlib.ContextDecorator "(in Python v3.15)"). * `django.utils._os.abspathu()` - Alias of [`os.path.abspath()`](https://docs.python.org/3/library/os.path.html#os.path.abspath "(in Python v3.15)"). * `django.utils._os.upath()` and `npath()` - These functions do nothing on Python 3. * `django.utils.six` - Remove usage of this vendored library or switch to [six](https://pypi.org/project/six/). * `django.utils.encoding.python_2_unicode_compatible()` - Alias of `six.python_2_unicode_compatible()`. * `django.utils.functional.curry()` - Use [`functools.partial()`](https://docs.python.org/3/library/functools.html#functools.partial "(in Python v3.15)") or [`functools.partialmethod`](https://docs.python.org/3/library/functools.html#functools.partialmethod "(in Python v3.15)"). See [5b1c389603a353625ae1603ba345147356336afb](https://github.com/django/django/commit/5b1c389603a353625ae1603ba345147356336afb). * `django.utils.safestring.SafeBytes` - Unused since Django 2.0. ### New default value for the `FILE_UPLOAD_PERMISSIONS` setting[¶](#new-default-value-for-the-file-upload-permissions-setting "Link to this heading") In older versions, the [`FILE_UPLOAD_PERMISSIONS`](../../ref/settings/#std-setting-FILE_UPLOAD_PERMISSIONS) setting defaults to `None`. With the default [`FILE_UPLOAD_HANDLERS`](../../ref/settings/#std-setting-FILE_UPLOAD_HANDLERS), this results in uploaded files having different permissions depending on their size and which upload handler is used. `FILE_UPLOAD_PERMISSIONS` now defaults to `0o644` to avoid this inconsistency. ### New default values for security settings[¶](#new-default-values-for-security-settings "Link to this heading") To make Django projects more secure by default, some security settings now have more secure default values: * [`X_FRAME_OPTIONS`](../../ref/settings/#std-setting-X_FRAME_OPTIONS) now defaults to `'DENY'`. * [`SECURE_CONTENT_TYPE_NOSNIFF`](../../ref/settings/#std-setting-SECURE_CONTENT_TYPE_NOSNIFF) now defaults to `True`. See the *What’s New* [Security section](#whats-new-security-3-0) above for more details on these changes. ### Miscellaneous[¶](#miscellaneous "Link to this heading") * `ContentType.__str__()` now includes the model’s `app_label` to disambiguate models with the same name in different apps. * Because accessing the language in the session rather than in the cookie is deprecated, `LocaleMiddleware` no longer looks for the user’s language in the session and [`django.contrib.auth.logout()`](../../topics/auth/default/#django.contrib.auth.logout "django.contrib.auth.logout") no longer preserves the session’s language after logout. * [`django.utils.html.escape()`](../../ref/utils/#django.utils.html.escape "django.utils.html.escape") now uses [`html.escape()`](https://docs.python.org/3/library/html.html#html.escape "(in Python v3.15)") to escape HTML. This converts `'` to `'` instead of the previous equivalent decimal code `'`. * The `django-admin test -k` option now works as the [`unittest -k`](https://docs.python.org/3/library/unittest.html#cmdoption-unittest-k "(in Python v3.15)") option rather than as a shortcut for `--keepdb`. * Support for `pywatchman` < 1.2.0 is removed. * [`urlencode()`](../../ref/utils/#django.utils.http.urlencode "django.utils.http.urlencode") now encodes iterable values as they are when `doseq=False`, rather than iterating them, bringing it into line with the standard library [`urllib.parse.urlencode()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlencode "(in Python v3.15)") function. * `intword` template filter now translates `1.0` as a singular phrase and all other numeric values as plural. This may be incorrect for some languages. * Assigning a value to a model’s [`ForeignKey`](../../ref/models/fields/#django.db.models.ForeignKey "django.db.models.ForeignKey") or [`OneToOneField`](../../ref/models/fields/#django.db.models.OneToOneField "django.db.models.OneToOneField") `'_id'` attribute now unsets the corresponding field. Accessing the field afterward will result in a query. * [`patch_vary_headers()`](../../ref/utils/#django.utils.cache.patch_vary_headers "django.utils.cache.patch_vary_headers") now handles an asterisk `'*'` according to [**RFC 7231 Section 7.1.4**](https://datatracker.ietf.org/doc/html/rfc7231.html#section-7.1.4), i.e. if a list of header field names contains an asterisk, then the `Vary` header will consist of a single asterisk `'*'`. * On MySQL 8.0.16+, `PositiveIntegerField` and `PositiveSmallIntegerField` now include a check constraint to prevent negative values in the database. * `alias=None` is added to the signature of [`Expression.get_group_by_cols()`](../../ref/models/expressions/#django.db.models.Expression.get_group_by_cols "django.db.models.Expression.get_group_by_cols"). * `RegexPattern`, used by [`re_path()`](../../ref/urls/#django.urls.re_path "django.urls.re_path"), no longer returns keyword arguments with `None` values to be passed to the view for the optional named groups that are missing. ## Features deprecated in 3.0[¶](#features-deprecated-in-3-0 "Link to this heading") ### `django.utils.encoding.force_text()` and `smart_text()`[¶](#django-utils-encoding-force-text-and-smart-text "Link to this heading") The `smart_text()` and `force_text()` aliases (since Django 2.0) of `smart_str()` and `force_str()` are deprecated. Ignore this deprecation if your code supports Python 2 as the behavior of `smart_str()` and `force_str()` is different there. ### Miscellaneous[¶](#id3 "Link to this heading") * `django.utils.http.urlquote()`, `urlquote_plus()`, `urlunquote()`, and `urlunquote_plus()` are deprecated in favor of the functions that they’re aliases for: [`urllib.parse.quote()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote "(in Python v3.15)"), [`quote_plus()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote_plus "(in Python v3.15)"), [`unquote()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.unquote "(in Python v3.15)"), and [`unquote_plus()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.unquote_plus "(in Python v3.15)"). * `django.utils.translation.ugettext()`, `ugettext_lazy()`, `ugettext_noop()`, `ungettext()`, and `ungettext_lazy()` are deprecated in favor of the functions that they’re aliases for: [`django.utils.translation.gettext()`](../../ref/utils/#django.utils.translation.gettext "django.utils.translation.gettext"), [`gettext_lazy()`](../../ref/utils/#django.utils.translation.gettext_lazy "django.utils.translation.gettext_lazy"), [`gettext_noop()`](../../ref/utils/#django.utils.translation.gettext_noop "django.utils.translation.gettext_noop"), [`ngettext()`](../../ref/utils/#django.utils.translation.ngettext "django.utils.translation.ngettext"), and [`ngettext_lazy()`](../../ref/utils/#django.utils.translation.ngettext_lazy "django.utils.translation.ngettext_lazy"). * To limit creation of sessions and hence favor some caching strategies, [`django.views.i18n.set_language()`](../../topics/i18n/translation/#django.views.i18n.set_language "django.views.i18n.set_language") will stop setting the user’s language in the session in Django 4.0. Since Django 2.1, the language is always stored in the [`LANGUAGE_COOKIE_NAME`](../../ref/settings/#std-setting-LANGUAGE_COOKIE_NAME) cookie. * `django.utils.text.unescape_entities()` is deprecated in favor of [`html.unescape()`](https://docs.python.org/3/library/html.html#html.unescape "(in Python v3.15)"). Note that unlike `unescape_entities()`, `html.unescape()` evaluates lazy strings immediately. * To avoid possible confusion as to effective scope, the private internal utility `is_safe_url()` is renamed to `url_has_allowed_host_and_scheme()`. That a URL has an allowed host and scheme doesn’t in general imply that it’s “safe”. It may still be quoted incorrectly, for example. Ensure to also use [`iri_to_uri()`](../../ref/utils/#django.utils.encoding.iri_to_uri "django.utils.encoding.iri_to_uri") on the path component of untrusted URLs. ## Features removed in 3.0[¶](#features-removed-in-3-0 "Link to this heading") These features have reached the end of their deprecation cycle and are removed in Django 3.0. See [Features deprecated in 2.0](../2.0/#deprecated-features-2-0) for details on these changes, including how to remove usage of these features. * The `django.db.backends.postgresql_psycopg2` module is removed. * `django.shortcuts.render_to_response()` is removed. * The `DEFAULT_CONTENT_TYPE` setting is removed. * `HttpRequest.xreadlines()` is removed. * Support for the `context` argument of `Field.from_db_value()` and `Expression.convert_value()` is removed. * The `field_name` keyword argument of `QuerySet.earliest()` and `latest()` is removed. See [Features deprecated in 2.1](../2.1/#deprecated-features-2-1) for details on these changes, including how to remove usage of these features. * The `ForceRHR` GIS function is removed. * `django.utils.http.cookie_date()` is removed. * The `staticfiles` and `admin_static` template tag libraries are removed. * `django.contrib.staticfiles.templatetags.staticfiles.static()` is removed. [**Back to Top](#top) ## Additional Information ### Support Django! * [Sam Huang donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 3.0 release notes](#) * [Python compatibility](#python-compatibility) * [Third-party library support for older version of Django](#third-party-library-support-for-older-version-of-django) * [What’s new in Django 3.0](#what-s-new-in-django-3-0) * [MariaDB support](#mariadb-support) * [ASGI support](#asgi-support) * [Exclusion constraints on PostgreSQL](#exclusion-constraints-on-postgresql) * [Filter expressions](#filter-expressions) * [Enumerations for model field choices](#enumerations-for-model-field-choices) * [Minor features](#minor-features) * [`django.contrib.admin`](#django-contrib-admin) * [`django.contrib.auth`](#django-contrib-auth) * [`django.contrib.gis`](#django-contrib-gis) * [`django.contrib.postgres`](#django-contrib-postgres) * [`django.contrib.sessions`](#django-contrib-sessions) * [`django.contrib.syndication`](#django-contrib-syndication) * [Cache](#cache) * [File Storage](#file-storage) * [Forms](#forms) * [Internationalization](#internationalization) * [Logging](#logging) * [Management Commands](#management-commands) * [Models](#models) * [Requests and Responses](#requests-and-responses) * [Security](#security) * [Tests](#tests) * [Backwards incompatible changes in 3.0](#backwards-incompatible-changes-in-3-0) * [`Model.save()` when providing a default for the primary key](#model-save-when-providing-a-default-for-the-primary-key) * [Database backend API](#database-backend-api) * [`django.contrib.admin`](#id1) * [`django.contrib.gis`](#id2) * [Dropped support for PostgreSQL 9.4](#dropped-support-for-postgresql-9-4) * [Dropped support for Oracle 12.1](#dropped-support-for-oracle-12-1) * [Removed private Python 2 compatibility APIs](#removed-private-python-2-compatibility-apis) * [New default value for the `FILE_UPLOAD_PERMISSIONS` setting](#new-default-value-for-the-file-upload-permissions-setting) * [New default values for security settings](#new-default-values-for-security-settings) * [Miscellaneous](#miscellaneous) * [Features deprecated in 3.0](#features-deprecated-in-3-0) * [`django.utils.encoding.force_text()` and `smart_text()`](#django-utils-encoding-force-text-and-smart-text) * [Miscellaneous](#id3) * [Features removed in 3.0](#features-removed-in-3-0) ---- url: https://docs.djangoproject.com/en/6.1/releases/4.2.4/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/4.2.4/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/4.2.4/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/4.2.4/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/4.2.4/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/4.2.4/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/4.2.4/) - [it](https://docs.djangoproject.com/it/6.1/releases/4.2.4/) - [id](https://docs.djangoproject.com/id/6.1/releases/4.2.4/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/4.2.4/) - [es](https://docs.djangoproject.com/es/6.1/releases/4.2.4/) - [el](https://docs.djangoproject.com/el/6.1/releases/4.2.4/) * * [dev](https://docs.djangoproject.com/en/dev/releases/4.2.4/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/4.2.4/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/4.2.4/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/4.2.4/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/4.2.4/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/4.2.4/) - [**](#top) # Django 4.2.4 release notes[¶](#django-4-2-4-release-notes "Link to this heading") *August 1, 2023* Django 4.2.4 fixes several bugs in 4.2.3. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a regression in Django 4.2 that caused a crash of `QuerySet.aggregate()` with aggregates referencing window functions ([#34717](https://code.djangoproject.com/ticket/34717)). * Fixed a regression in Django 4.2 that caused a crash when grouping by a reference in a subquery ([#34748](https://code.djangoproject.com/ticket/34748)). * Fixed a regression in Django 4.2 that caused aggregation over query that uses explicit grouping by multi-valued annotations to group against the wrong columns ([#34750](https://code.djangoproject.com/ticket/34750)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Win Htet Aung donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 4.2.4 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/topics/composite-primary-key/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/composite-primary-key/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/composite-primary-key/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/composite-primary-key/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/composite-primary-key/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/composite-primary-key/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/composite-primary-key/) - [it](https://docs.djangoproject.com/it/6.1/topics/composite-primary-key/) - [id](https://docs.djangoproject.com/id/6.1/topics/composite-primary-key/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/composite-primary-key/) - [es](https://docs.djangoproject.com/es/6.1/topics/composite-primary-key/) - [el](https://docs.djangoproject.com/el/6.1/topics/composite-primary-key/) * * [dev](https://docs.djangoproject.com/en/dev/topics/composite-primary-key/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/composite-primary-key/) * [5.2](https://docs.djangoproject.com/en/5.2/topics/composite-primary-key/) - [**](#top) # Composite primary keys[¶](#composite-primary-keys "Link to this heading") In Django, each model has a primary key. By default, this primary key consists of a single field. In most cases, a single primary key should suffice. In database design, however, defining a primary key consisting of multiple fields is sometimes necessary. To use a composite primary key, when defining a model set the `pk` attribute to be a [`CompositePrimaryKey`](../../ref/models/fields/#django.db.models.CompositePrimaryKey "django.db.models.CompositePrimaryKey"): ``` class Product(models.Model): name = models.CharField(max_length=100) class Order(models.Model): reference = models.CharField(max_length=20, primary_key=True) class OrderLineItem(models.Model): pk = models.CompositePrimaryKey("product_id", "order_id") product = models.ForeignKey(Product, on_delete=models.CASCADE) order = models.ForeignKey(Order, on_delete=models.CASCADE) quantity = models.IntegerField() ``` This will instruct Django to create a composite primary key (`PRIMARY KEY (product_id, order_id)`) when creating the table. A composite primary key is represented by a `tuple`: ``` >>> product = Product.objects.create(name="apple") >>> order = Order.objects.create(reference="A755H") >>> item = OrderLineItem.objects.create(product=product, order=order, quantity=1) >>> item.pk (1, "A755H") ``` You can assign a `tuple` to the [`pk`](../../ref/models/instances/#django.db.models.Model.pk "django.db.models.Model.pk") attribute. This sets the associated field values: ``` >>> item = OrderLineItem(pk=(2, "B142C")) >>> item.pk (2, "B142C") >>> item.product_id 2 >>> item.order_id "B142C" ``` A composite primary key can also be filtered by a `tuple`: ``` >>> OrderLineItem.objects.filter(pk=(1, "A755H")).count() 1 ``` We’re still working on composite primary key support for [relational fields](#cpk-and-relations), including [`GenericForeignKey`](../../ref/contrib/contenttypes/#django.contrib.contenttypes.fields.GenericForeignKey "django.contrib.contenttypes.fields.GenericForeignKey") fields, and the Django admin. Models with composite primary keys cannot be registered in the Django admin at this time. You can expect to see this in future releases. ## Migrating to a composite primary key[¶](#migrating-to-a-composite-primary-key "Link to this heading") Django doesn’t support migrating to, or from, a composite primary key after the table is created. It also doesn’t support adding or removing fields from the composite primary key. If you would like to migrate an existing table from a single primary key to a composite primary key, follow your database backend’s instructions to do so. Once the composite primary key is in place, add the `CompositePrimaryKey` field to your model. This allows Django to recognize and handle the composite primary key appropriately. While migration operations (e.g. `AddField`, `AlterField`) on primary key fields are not supported, `makemigrations` will still detect changes. In order to avoid errors, it’s recommended to apply such migrations with `--fake`. Alternatively, [`SeparateDatabaseAndState`](../../ref/migration-operations/#django.db.migrations.operations.SeparateDatabaseAndState "django.db.migrations.operations.SeparateDatabaseAndState") may be used to execute the backend-specific migrations and Django-generated migrations in a single operation. ## Composite primary keys and relations[¶](#composite-primary-keys-and-relations "Link to this heading") [Relationship fields](../../ref/models/fields/#relationship-fields), including [generic relations](../../ref/contrib/contenttypes/#generic-relations) do not support composite primary keys. For example, given the `OrderLineItem` model, the following is not supported: ``` class Foo(models.Model): item = models.ForeignKey(OrderLineItem, on_delete=models.CASCADE) ``` Because `ForeignKey` currently cannot reference models with composite primary keys. To work around this limitation, `ForeignObject` can be used as an alternative: ``` class Foo(models.Model): item_order_id = models.CharField(max_length=20) item_product_id = models.IntegerField() item = models.ForeignObject( OrderLineItem, on_delete=models.CASCADE, from_fields=("item_order_id", "item_product_id"), to_fields=("order_id", "product_id"), ) ``` `ForeignObject` is much like `ForeignKey`, except that it doesn’t create any columns (e.g. `item_id`), foreign key constraints or indexes in the database, and the `on_delete` argument is ignored. ## Composite primary keys and database functions[¶](#composite-primary-keys-and-database-functions "Link to this heading") Many database functions only accept a single expression. ``` MAX("order_id") -- OK MAX("product_id", "order_id") -- ERROR ``` In these cases, providing a composite primary key reference raises a `ValueError`, since it is composed of multiple column expressions. An exception is made for `Count`. ``` Max("order_id") # OK Max("pk") # ValueError Count("pk") # OK ``` ## Composite primary keys in forms[¶](#composite-primary-keys-in-forms "Link to this heading") As a composite primary key is a virtual field, a field which doesn’t represent a single database column, this field is excluded from ModelForms. For example, take the following form: ``` class OrderLineItemForm(forms.ModelForm): class Meta: model = OrderLineItem fields = "__all__" ``` This form does not have a form field `pk` for the composite primary key: ``` >>> OrderLineItemForm() ``` Setting the primary composite field `pk` as a form field raises an unknown field [`FieldError`](../../ref/exceptions/#django.core.exceptions.FieldError "django.core.exceptions.FieldError"). Primary key fields are read only If you change the value of a primary key on an existing object and then save it, a new object will be created alongside the old one (see [`Field.primary_key`](../../ref/models/fields/#django.db.models.Field.primary_key "django.db.models.Field.primary_key")). This is also true of composite primary keys. Hence, you may want to set [`Field.editable`](../../ref/models/fields/#django.db.models.Field.editable "django.db.models.Field.editable") to `False` on all primary key fields to exclude them from ModelForms. ## Composite primary keys in model validation[¶](#composite-primary-keys-in-model-validation "Link to this heading") Since `pk` is only a virtual field, including `pk` as a field name in the `exclude` argument of [`Model.clean_fields()`](../../ref/models/instances/#django.db.models.Model.clean_fields "django.db.models.Model.clean_fields") has no effect. To exclude the composite primary key fields from [model validation](../../ref/models/instances/#validating-objects), specify each field individually. [`Model.validate_unique()`](../../ref/models/instances/#django.db.models.Model.validate_unique "django.db.models.Model.validate_unique") can still be called with `exclude={"pk"}` to skip uniqueness checks. ## Building composite primary key ready applications[¶](#building-composite-primary-key-ready-applications "Link to this heading") Prior to the introduction of composite primary keys, the single field composing the primary key of a model could be retrieved by introspecting the [`primary_key`](../../ref/models/fields/#django.db.models.Field.primary_key "django.db.models.Field.primary_key") attribute of its fields: ``` >>> pk_field = None >>> for field in Product._meta.get_fields(): ... if field.primary_key: ... pk_field = field ... break ... >>> pk_field ``` Now that a primary key can be composed of multiple fields the [`primary_key`](../../ref/models/fields/#django.db.models.Field.primary_key "django.db.models.Field.primary_key") attribute can no longer be relied upon to identify members of the primary key as it will be set to `False` to maintain the invariant that at most one field per model will have this attribute set to `True`: ``` >>> pk_fields = [] >>> for field in OrderLineItem._meta.get_fields(): ... if field.primary_key: ... pk_fields.append(field) ... >>> pk_fields [] ``` In order to build application code that properly handles composite primary keys the [`_meta.pk_fields`](../../ref/models/meta/#django.db.models.options.Options.pk_fields "django.db.models.options.Options.pk_fields") attribute should be used instead: ``` >>> Product._meta.pk_fields [] >>> OrderLineItem._meta.pk_fields [ , ] ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [GratisGokken donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Composite primary keys](#) * [Migrating to a composite primary key](#migrating-to-a-composite-primary-key) * [Composite primary keys and relations](#composite-primary-keys-and-relations) * [Composite primary keys and database functions](#composite-primary-keys-and-database-functions) * [Composite primary keys in forms](#composite-primary-keys-in-forms) * [Composite primary keys in model validation](#composite-primary-keys-in-model-validation) * [Building composite primary key ready applications](#building-composite-primary-key-ready-applications) ---- url: https://docs.djangoproject.com/en/6.1/topics/testing/tools/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/testing/tools/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/testing/tools/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/testing/tools/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/testing/tools/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/testing/tools/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/testing/tools/) - [it](https://docs.djangoproject.com/it/6.1/topics/testing/tools/) - [id](https://docs.djangoproject.com/id/6.1/topics/testing/tools/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/testing/tools/) - [es](https://docs.djangoproject.com/es/6.1/topics/testing/tools/) - [el](https://docs.djangoproject.com/el/6.1/topics/testing/tools/) * * [dev](https://docs.djangoproject.com/en/dev/topics/testing/tools/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/testing/tools/) * [5.2](https://docs.djangoproject.com/en/5.2/topics/testing/tools/) * [5.1](https://docs.djangoproject.com/en/5.1/topics/testing/tools/) * [5.0](https://docs.djangoproject.com/en/5.0/topics/testing/tools/) * [4.2](https://docs.djangoproject.com/en/4.2/topics/testing/tools/) * [4.1](https://docs.djangoproject.com/en/4.1/topics/testing/tools/) * [4.0](https://docs.djangoproject.com/en/4.0/topics/testing/tools/) * [3.2](https://docs.djangoproject.com/en/3.2/topics/testing/tools/) * [3.1](https://docs.djangoproject.com/en/3.1/topics/testing/tools/) * [3.0](https://docs.djangoproject.com/en/3.0/topics/testing/tools/) * [2.2](https://docs.djangoproject.com/en/2.2/topics/testing/tools/) * [2.1](https://docs.djangoproject.com/en/2.1/topics/testing/tools/) * [2.0](https://docs.djangoproject.com/en/2.0/topics/testing/tools/) * [1.11](https://docs.djangoproject.com/en/1.11/topics/testing/tools/) * [1.10](https://docs.djangoproject.com/en/1.10/topics/testing/tools/) * [1.9](https://docs.djangoproject.com/en/1.9/topics/testing/tools/) * [1.8](https://docs.djangoproject.com/en/1.8/topics/testing/tools/) - [**](#top) # Testing tools[¶](#testing-tools "Link to this heading") Django provides a small set of tools that come in handy when writing tests. There are community-maintained solutions! Django has a vibrant ecosystem. There are testing and fixtures solutions highlighted on the [Community Ecosystem](https://www.djangoproject.com/community/ecosystem/#testing-fixtures) page. The Django Packages [Testing tools grid](https://djangopackages.org/grids/g/testing/) has even more options for you! ## The test client[¶](#the-test-client "Link to this heading") The test client is a Python class that acts as a dummy web browser, allowing you to test your views and interact with your Django-powered application programmatically. Some of the things you can do with the test client are: * Simulate GET and POST requests on a URL and observe the response – everything from low-level HTTP (result headers and status codes) to page content. * See the chain of redirects (if any) and check the URL and status code at each step. * Test that a given request is rendered by a given Django template, with a template context that contains certain values. Note that the test client is not intended to be a replacement for [Selenium](https://www.selenium.dev/) or other “in-browser” frameworks. Django’s test client has a different focus. In short: * Use Django’s test client to establish that the correct template is being rendered and that the template is passed the correct context data. * Use [`RequestFactory`](../advanced/#django.test.RequestFactory "django.test.RequestFactory") to test view functions directly, bypassing the routing and middleware layers. * Use in-browser frameworks like [Selenium](https://www.selenium.dev/) to test *rendered* HTML and the *behavior* of web pages, namely JavaScript functionality. Django also provides special support for those frameworks; see the section on [`LiveServerTestCase`](#django.test.LiveServerTestCase "django.test.LiveServerTestCase") for more details. A comprehensive test suite should use a combination of all of these test types. ### Overview and a quick example[¶](#overview-and-a-quick-example "Link to this heading") To use the test client, instantiate `django.test.Client` and retrieve web pages: ``` >>> from django.test import Client >>> c = Client() >>> response = c.post("/login/", {"username": "john", "password": "smith"}) >>> response.status_code 200 >>> response = c.get("/customer/details/") >>> response.content b'>> c.get("/login/") ``` This is incorrect: ``` >>> c.get("https://www.example.com/login/") ``` The test client is not capable of retrieving web pages that are not powered by your Django project. If you need to retrieve other web pages, use a Python standard library module such as [`urllib`](https://docs.python.org/3/library/urllib.html#module-urllib "(in Python v3.15)"). * To resolve URLs, the test client uses whatever URLconf is pointed-to by your [`ROOT_URLCONF`](../../../ref/settings/#std-setting-ROOT_URLCONF) setting. * Although the above example would work in the Python interactive interpreter, some of the test client’s functionality, notably the template-related functionality, is only available *while tests are running*. The reason for this is that Django’s test runner performs a bit of black magic in order to determine which template was loaded by a given view. This black magic (essentially a patching of Django’s template system in memory) only happens during test running. * By default, the test client will disable any CSRF checks performed by your site. If, for some reason, you *want* the test client to perform CSRF checks, you can create an instance of the test client that enforces CSRF checks. To do this, pass in the `enforce_csrf_checks` argument when you construct your client: ``` >>> from django.test import Client >>> csrf_client = Client(enforce_csrf_checks=True) ``` ### Making requests[¶](#making-requests "Link to this heading") Use the `django.test.Client` class to make requests. * *class *Client(*enforce\_csrf\_checks=False*, *raise\_request\_exception=True*, *json\_encoder=DjangoJSONEncoder*, *\**, *headers=None*, *query\_params=None*, *\*\*defaults*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/client.py#L1032)[¶](#django.test.Client "Link to this definition") A testing HTTP client. Takes several arguments that can customize behavior. `headers` allows you to specify default headers that will be sent with every request. For example, to set a `User-Agent` header: ``` client = Client(headers={"user-agent": "curl/7.79.1"}) ``` `query_params` allows you to specify the default query string that will be set on every request. Arbitrary keyword arguments in `**defaults` set WSGI [**environ variables**](https://peps.python.org/pep-3333/#environ-variables). For example, to set the script name: ``` client = Client(SCRIPT_NAME="/app/") ``` Note Keyword arguments starting with a `HTTP_` prefix are set as headers, but the `headers` parameter should be preferred for readability. The values from the `headers`, `query_params`, and `extra` keyword arguments passed to [`get()`](#django.test.Client.get "django.test.Client.get"), [`post()`](#django.test.Client.post "django.test.Client.post"), etc. have precedence over the defaults passed to the class constructor. The `enforce_csrf_checks` argument can be used to test CSRF protection (see above). The `raise_request_exception` argument allows controlling whether or not exceptions raised during the request should also be raised in the test. Defaults to `True`. The `json_encoder` argument allows setting a custom JSON encoder for the JSON serialization that’s described in [`post()`](#django.test.Client.post "django.test.Client.post"). Once you have a `Client` instance, you can call any of the following methods: * get(*path*, *data=None*, *follow=False*, *secure=False*, *\**, *headers=None*, *query\_params=None*, *\*\*extra*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/client.py#L1114)[¶](#django.test.Client.get "Link to this definition") Makes a GET request on the provided `path` and returns a `Response` object, which is documented below. The key-value pairs in the `query_params` dictionary are used to set query strings. For example: ``` >>> c = Client() >>> c.get("/customers/details/", query_params={"name": "fred", "age": 7}) ``` …will result in the evaluation of a GET request equivalent to: ``` /customers/details/?name=fred&age=7 ``` It is also possible to pass these parameters into the `data` parameter. However, `query_params` is preferred as it works for any HTTP method. The `headers` parameter can be used to specify headers to be sent in the request. For example: ``` >>> c = Client() >>> c.get( ... "/customers/details/", ... query_params={"name": "fred", "age": 7}, ... headers={"accept": "application/json"}, ... ) ``` …will send the HTTP header `HTTP_ACCEPT` to the details view, which is a good way to test code paths that use the [`django.http.HttpRequest.accepts()`](../../../ref/request-response/#django.http.HttpRequest.accepts "django.http.HttpRequest.accepts") method. Arbitrary keyword arguments set WSGI [**environ variables**](https://peps.python.org/pep-3333/#environ-variables). For example, headers to set the script name: ``` >>> c = Client() >>> c.get("/", SCRIPT_NAME="/app/") ``` If you already have the GET arguments in URL-encoded form, you can use that encoding instead of using the data argument. For example, the previous GET request could also be posed as: ``` >>> c = Client() >>> c.get("/customers/details/?name=fred&age=7") ``` If you provide a URL with both an encoded GET data and either a query\_params or data argument these arguments will take precedence. If you set `follow` to `True` the client will follow any redirects and a `redirect_chain` attribute will be set in the response object containing tuples of the intermediate urls and status codes. If you had a URL `/redirect_me/` that redirected to `/next/`, that redirected to `/final/`, this is what you’d see: ``` >>> response = c.get("/redirect_me/", follow=True) >>> response.redirect_chain [('http://testserver/next/', 302), ('http://testserver/final/', 302)] ``` If you set `secure` to `True` the client will emulate an HTTPS request. - post(*path*, *data=None*, *content\_type=MULTIPART\_CONTENT*, *follow=False*, *secure=False*, *\**, *headers=None*, *query\_params=None*, *\*\*extra*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/client.py#L1142)[¶](#django.test.Client.post "Link to this definition") Makes a POST request on the provided `path` and returns a `Response` object, which is documented below. The key-value pairs in the `data` dictionary are used to submit POST data. For example: ``` >>> c = Client() >>> c.post("/login/", {"name": "fred", "passwd": "secret"}) ``` …will result in the evaluation of a POST request to this URL: ``` /login/ ``` …with this POST data: ``` name=fred&passwd=secret ``` If you provide `content_type` as *application/json*, the `data` is serialized using [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps "(in Python v3.15)") if it’s a dict, list, or tuple. Serialization is performed with [`DjangoJSONEncoder`](../../serialization/#django.core.serializers.json.DjangoJSONEncoder "django.core.serializers.json.DjangoJSONEncoder") by default, and can be overridden by providing a `json_encoder` argument to [`Client`](#django.test.Client "django.test.Client"). This serialization also happens for [`put()`](#django.test.Client.put "django.test.Client.put"), [`patch()`](#django.test.Client.patch "django.test.Client.patch"), and [`delete()`](#django.test.Client.delete "django.test.Client.delete") requests. If you provide any other `content_type` (e.g. *text/xml* for an XML payload), the contents of `data` are sent as-is in the POST request, using `content_type` in the HTTP `Content-Type` header. If you don’t provide a value for `content_type`, the values in `data` will be transmitted with a content type of *multipart/form-data*. In this case, the key-value pairs in `data` will be encoded as a multipart message and used to create the POST data payload. To submit multiple values for a given key – for example, to specify the selections for a `', '', ) ``` `html1` and `html2` must contain HTML. An `AssertionError` will be raised if one of them cannot be parsed. Output in case of error can be customized with the `msg` argument. * SimpleTestCase.assertHTMLNotEqual(*html1*, *html2*, *msg=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L979)[¶](#django.test.SimpleTestCase.assertHTMLNotEqual "Link to this definition") Asserts that the strings `html1` and `html2` are *not* equal. The comparison is based on HTML semantics. See [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual "django.test.SimpleTestCase.assertHTMLEqual") for details. `html1` and `html2` must contain HTML. An `AssertionError` will be raised if one of them cannot be parsed. Output in case of error can be customized with the `msg` argument. - SimpleTestCase.assertXMLEqual(*xml1*, *xml2*, *msg=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1063)[¶](#django.test.SimpleTestCase.assertXMLEqual "Link to this definition") Asserts that the strings `xml1` and `xml2` are equal. The comparison is based on XML semantics. Similarly to [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual "django.test.SimpleTestCase.assertHTMLEqual"), the comparison is made on parsed content, hence only semantic differences are considered, not syntax differences. When invalid XML is passed in any parameter, an `AssertionError` is always raised, even if both strings are identical. XML declaration, document type, processing instructions, and comments are ignored. Only the root element and its children are compared. Output in case of error can be customized with the `msg` argument. * SimpleTestCase.assertXMLNotEqual(*xml1*, *xml2*, *msg=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1086)[¶](#django.test.SimpleTestCase.assertXMLNotEqual "Link to this definition") Asserts that the strings `xml1` and `xml2` are *not* equal. The comparison is based on XML semantics. See [`assertXMLEqual()`](#django.test.SimpleTestCase.assertXMLEqual "django.test.SimpleTestCase.assertXMLEqual") for details. Output in case of error can be customized with the `msg` argument. - SimpleTestCase.assertInHTML(*needle*, *haystack*, *count=None*, *msg\_prefix=''*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L992)[¶](#django.test.SimpleTestCase.assertInHTML "Link to this definition") Asserts that the HTML fragment `needle` is contained in the `haystack` once. If the `count` integer argument is specified, then additionally the number of `needle` occurrences will be strictly verified. Whitespace in most cases is ignored, and attribute ordering is not significant. See [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual "django.test.SimpleTestCase.assertHTMLEqual") for more details. * SimpleTestCase.assertNotInHTML(*needle*, *haystack*, *msg\_prefix=''*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1026)[¶](#django.test.SimpleTestCase.assertNotInHTML "Link to this definition") Asserts that the HTML fragment `needle` is *not* contained in the `haystack`. Whitespace in most cases is ignored, and attribute ordering is not significant. See [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual "django.test.SimpleTestCase.assertHTMLEqual") for more details. - SimpleTestCase.assertJSONEqual(*raw*, *expected\_data*, *msg=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1029)[¶](#django.test.SimpleTestCase.assertJSONEqual "Link to this definition") Asserts that the JSON fragments `raw` and `expected_data` are equal. Usual JSON non-significant whitespace rules apply as the heavyweight is delegated to the [`json`](https://docs.python.org/3/library/json.html#module-json "(in Python v3.15)") library. Output in case of error can be customized with the `msg` argument. * SimpleTestCase.assertJSONNotEqual(*raw*, *expected\_data*, *msg=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1046)[¶](#django.test.SimpleTestCase.assertJSONNotEqual "Link to this definition") Asserts that the JSON fragments `raw` and `expected_data` are *not* equal. See [`assertJSONEqual()`](#django.test.SimpleTestCase.assertJSONEqual "django.test.SimpleTestCase.assertJSONEqual") for further details. Output in case of error can be customized with the `msg` argument. - TransactionTestCase.assertQuerySetEqual(*qs*, *values*, *transform=None*, *ordered=True*, *msg=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1288)[¶](#django.test.TransactionTestCase.assertQuerySetEqual "Link to this definition") Asserts that a queryset `qs` matches a particular iterable of values `values`. If `transform` is provided, `values` is compared to a list produced by applying `transform` to each member of `qs`. By default, the comparison is also ordering dependent. If `qs` doesn’t provide an implicit ordering, you can set the `ordered` parameter to `False`, which turns the comparison into a `collections.Counter` comparison. If the order is undefined (if the given `qs` isn’t ordered and the comparison is against more than one ordered value), a `ValueError` is raised. Output in case of error can be customized with the `msg` argument. * TransactionTestCase.assertNumQueries(*num*, *func*, *\*args*, *\*\*kwargs*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1304)[¶](#django.test.TransactionTestCase.assertNumQueries "Link to this definition") Asserts that when `func` is called with `*args` and `**kwargs` that `num` database queries are executed. If a `"using"` key is present in `kwargs` it is used as the database alias for which to check the number of queries: ``` self.assertNumQueries(7, my_function, using="non_default_db") ``` If you wish to call a function with a `using` parameter you can do it by wrapping the call with a `lambda` to add an extra parameter: ``` self.assertNumQueries(7, lambda: my_function(using=7)) ``` You can also use this as a context manager: ``` with self.assertNumQueries(2): Person.objects.create(name="Aaron") Person.objects.create(name="Daniel") ``` ### Tagging tests[¶](#tagging-tests "Link to this heading") You can tag your tests so you can easily run a particular subset. For example, you might label fast or slow tests: ``` from django.test import tag class SampleTestCase(TestCase): @tag("fast") def test_fast(self): ... @tag("slow") def test_slow(self): ... @tag("slow", "core") def test_slow_but_core(self): ... ``` You can also tag a test case class: ``` @tag("slow", "core") class SampleTestCase(TestCase): ... ``` Subclasses inherit tags from superclasses, and methods inherit tags from their class. Given: ``` @tag("foo") class SampleTestCaseChild(SampleTestCase): @tag("bar") def test(self): ... ``` `SampleTestCaseChild.test` will be labeled with `'slow'`, `'core'`, `'bar'`, and `'foo'`. Then you can choose which tests to run. For example, to run only fast tests: /  ``` $ ./manage.py test --tag=fast ``` ** ``` ...\> manage.py test --tag=fast ``` ** Or to run fast tests and the core one (even though it’s slow): /  ``` $ ./manage.py test --tag=fast --tag=core ``` ** ``` ...\> manage.py test --tag=fast --tag=core ``` ** You can also exclude tests by tag. To run core tests if they are not slow: /  ``` $ ./manage.py test --tag=core --exclude-tag=slow ``` ** ``` ...\> manage.py test --tag=core --exclude-tag=slow ``` ** [`test --exclude-tag`](../../../ref/django-admin/#cmdoption-test-exclude-tag) has precedence over [`test --tag`](../../../ref/django-admin/#cmdoption-test-tag), so if a test has two tags and you select one of them and exclude the other, the test won’t be run. ## Testing asynchronous code[¶](#testing-asynchronous-code "Link to this heading") If you merely want to test the output of your asynchronous views, the standard test client will run them inside their own asynchronous loop without any extra work needed on your part. However, if you want to write fully-asynchronous tests for a Django project, you will need to take several things into account. Firstly, your tests must be `async def` methods on the test class (in order to give them an asynchronous context). Django will automatically detect any `async def` tests and wrap them so they run in their own event loop. If you are testing from an asynchronous function, you must also use the asynchronous test client. This is available as `django.test.AsyncClient`, or as `self.async_client` on any test. * *class *AsyncClient(*enforce\_csrf\_checks=False*, *raise\_request\_exception=True*, *\**, *headers=None*, *query\_params=None*, *\*\*defaults*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/client.py#L1401)[¶](#django.test.AsyncClient "Link to this definition") `AsyncClient` has the same methods and signatures as the synchronous (normal) test client, with the following exceptions: * In the initialization, arbitrary keyword arguments in `defaults` are added directly into the ASGI scope. * Headers passed as `extra` keyword arguments should not have the `HTTP_` prefix required by the synchronous client (see [`Client.get()`](#django.test.Client.get "django.test.Client.get")). For example, here is how to set an HTTP `Accept` header: ``` >>> c = AsyncClient() >>> c.get("/customers/details/", {"name": "fred", "age": 7}, ACCEPT="application/json") ``` Using `AsyncClient` any method that makes a request must be awaited: ``` async def test_my_thing(self): response = await self.async_client.get("/some-url/") self.assertEqual(response.status_code, 200) ``` The asynchronous client can also call synchronous views; it runs through Django’s [asynchronous request path](../../async/), which supports both. Any view called through the `AsyncClient` will get an `ASGIRequest` object for its `request` rather than the `WSGIRequest` that the normal client creates. Warning If you are using test decorators, they must be async-compatible to ensure they work correctly. Django’s built-in decorators will behave correctly, but third-party ones may appear to not execute (they will “wrap” the wrong part of the execution flow and not your test). If you need to use these decorators, then you should decorate your test methods with [`async_to_sync()`](../../async/#asgiref.sync.async_to_sync "asgiref.sync.async_to_sync") *inside* of them instead: ``` from asgiref.sync import async_to_sync from django.test import TestCase class MyTests(TestCase): @mock.patch(...) @async_to_sync async def test_my_thing(self): ... ``` ## Email services[¶](#email-services "Link to this heading") If any of your code sends email using [Django’s email functionality](../../email/), you probably don’t want to send email each time you run a test that exercises that code. For this reason, Django’s test runner automatically redirects all Django-sent email to an in-memory outbox. This lets you test every aspect of sending email – from the number of messages sent to the contents of each message – without actually sending the messages. The test runner accomplishes this by transparently replacing the [`BACKEND`](../../../ref/settings/#std-setting-MAILERS-BACKEND) for each configured [`MAILERS`](../../../ref/settings/#std-setting-MAILERS) alias with the `'locmem'` [memory email backend](../../email/#topic-email-memory-backend). (Don’t worry – this has no effect on any other email senders outside of Django, such as your machine’s mail server, if you’re running one.) * django.core.mail.outbox[¶](#django.core.mail.django.core.mail.outbox "Link to this definition") During test running, each outgoing email is saved in `django.core.mail.outbox`. This is a list of all [`EmailMessage`](../../email/#django.core.mail.EmailMessage "django.core.mail.EmailMessage") instances that have been sent. The `outbox` attribute is a special attribute that is created *only* when the `locmem` email backend is used. It doesn’t normally exist as part of the [`django.core.mail`](../../email/#module-django.core.mail "django.core.mail: Helpers to send email.") module and you can’t import it directly. The code below shows how to access this attribute correctly. Here’s an example test that examines `django.core.mail.outbox` for length and contents: ``` from django.core import mail from django.test import TestCase class EmailTest(TestCase): def test_send_email(self): # Send message. mail.send_mail( "Subject here", "Here is the message.", "from@example.com", ["to@example.com"], ) # Test that one message has been sent. self.assertEqual(len(mail.outbox), 1) # Verify that the subject of the first message is correct. self.assertEqual(mail.outbox[0].subject, "Subject here") # Verify the message was sent with the "default" mailer. self.assertEqual(mail.outbox[0].sent_using, "default") ``` Changed in Django 6.1: The `sent_using` attribute was added to messages in the outbox. As noted [previously](#emptying-test-outbox), the test outbox is emptied at the start of every test in a Django `*TestCase`. To empty the outbox manually, assign the empty list to `mail.outbox`: ``` from django.core import mail # Empty the test outbox mail.outbox = [] ``` ## Management Commands[¶](#management-commands "Link to this heading") Management commands can be tested with the [`call_command()`](../../../ref/django-admin/#django.core.management.call_command "django.core.management.call_command") function. The output can be redirected into a `StringIO` instance: ``` from io import StringIO from django.core.management import call_command from django.test import TestCase class ClosepollTest(TestCase): def test_command_output(self): out = StringIO() call_command("closepoll", poll_ids=[1], stdout=out) self.assertIn('Successfully closed poll "1"', out.getvalue()) ``` ## Skipping tests[¶](#skipping-tests "Link to this heading") The unittest library provides the [`@skipIf`](https://docs.python.org/3/library/unittest.html#unittest.skipIf "(in Python v3.15)") and [`@skipUnless`](https://docs.python.org/3/library/unittest.html#unittest.skipUnless "(in Python v3.15)") decorators to allow you to skip tests if you know ahead of time that those tests are going to fail under certain conditions. For example, if your test requires a particular optional library in order to succeed, you could decorate the test case with [`@skipIf`](https://docs.python.org/3/library/unittest.html#unittest.skipIf "(in Python v3.15)"). Then, the test runner will report that the test wasn’t executed and why, instead of failing the test or omitting the test altogether. To supplement these test skipping behaviors, Django provides two additional skip decorators. Instead of testing a generic boolean, these decorators check the capabilities of the database, and skip the test if the database doesn’t support a specific named feature. The decorators use a string identifier to describe database features. This string corresponds to attributes of the database connection features class. See [django.db.backends.base.features.BaseDatabaseFeatures class](https://github.com/django/django/blob/main/django/db/backends/base/features.py) for a full list of database features that can be used as a basis for skipping tests. * skipIfDBFeature(*\*feature\_name\_strings*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1623)[¶](#django.test.skipIfDBFeature "Link to this definition") Skip the decorated test or `TestCase` if all of the named database features are supported. For example, the following test will not be executed if the database supports transactions (e.g., it would *not* run under PostgreSQL, but it would under MySQL with MyISAM tables): ``` class MyTests(TestCase): @skipIfDBFeature("supports_transactions") def test_transaction_behavior(self): # ... conditional test code pass ``` * skipUnlessDBFeature(*\*feature\_name\_strings*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/test/testcases.py#L1632)[¶](#django.test.skipUnlessDBFeature "Link to this definition") Skip the decorated test or `TestCase` if any of the named database features are *not* supported. For example, the following test will only be executed if the database supports transactions (e.g., it would run under PostgreSQL, but *not* under MySQL with MyISAM tables): ``` class MyTests(TestCase): @skipUnlessDBFeature("supports_transactions") def test_transaction_behavior(self): # ... conditional test code pass ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [Houston Immigration Lawyers donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Testing tools](#) * [The test client](#the-test-client) * [Overview and a quick example](#overview-and-a-quick-example) * [Making requests](#making-requests) * [Testing responses](#testing-responses) * [Exceptions](#exceptions) * [Persistent state](#persistent-state) * [Setting the language](#setting-the-language) * [Example](#example) * [Provided test case classes](#provided-test-case-classes) * [`SimpleTestCase`](#simpletestcase) * [`TransactionTestCase`](#transactiontestcase) * [`TestCase`](#testcase) * [`LiveServerTestCase`](#liveservertestcase) * [Test cases features](#test-cases-features) * [Default test client](#default-test-client) * [Customizing the test client](#customizing-the-test-client) * [Fixture loading](#fixture-loading) * [URLconf configuration](#urlconf-configuration) * [Multi-database support](#multi-database-support) * [Overriding settings](#overriding-settings) * [Isolating apps](#isolating-apps) * [Emptying the test outbox](#emptying-the-test-outbox) * [Assertions](#assertions) * [Tagging tests](#tagging-tests) * [Testing asynchronous code](#testing-asynchronous-code) * [Email services](#email-services) * [Management Commands](#management-commands) * [Skipping tests](#skipping-tests) ---- url: https://docs.djangoproject.com/en/6.1/faq/troubleshooting/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/faq/troubleshooting/) - [sv](https://docs.djangoproject.com/sv/6.1/faq/troubleshooting/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/faq/troubleshooting/) - [pl](https://docs.djangoproject.com/pl/6.1/faq/troubleshooting/) - [ko](https://docs.djangoproject.com/ko/6.1/faq/troubleshooting/) - [ja](https://docs.djangoproject.com/ja/6.1/faq/troubleshooting/) - [it](https://docs.djangoproject.com/it/6.1/faq/troubleshooting/) - [id](https://docs.djangoproject.com/id/6.1/faq/troubleshooting/) - [fr](https://docs.djangoproject.com/fr/6.1/faq/troubleshooting/) - [es](https://docs.djangoproject.com/es/6.1/faq/troubleshooting/) - [el](https://docs.djangoproject.com/el/6.1/faq/troubleshooting/) * * [dev](https://docs.djangoproject.com/en/dev/faq/troubleshooting/) * [6.0](https://docs.djangoproject.com/en/6.0/faq/troubleshooting/) * [5.2](https://docs.djangoproject.com/en/5.2/faq/troubleshooting/) * [5.1](https://docs.djangoproject.com/en/5.1/faq/troubleshooting/) * [5.0](https://docs.djangoproject.com/en/5.0/faq/troubleshooting/) * [4.2](https://docs.djangoproject.com/en/4.2/faq/troubleshooting/) * [4.1](https://docs.djangoproject.com/en/4.1/faq/troubleshooting/) * [4.0](https://docs.djangoproject.com/en/4.0/faq/troubleshooting/) * [3.2](https://docs.djangoproject.com/en/3.2/faq/troubleshooting/) * [3.1](https://docs.djangoproject.com/en/3.1/faq/troubleshooting/) * [3.0](https://docs.djangoproject.com/en/3.0/faq/troubleshooting/) * [2.2](https://docs.djangoproject.com/en/2.2/faq/troubleshooting/) * [2.1](https://docs.djangoproject.com/en/2.1/faq/troubleshooting/) * [2.0](https://docs.djangoproject.com/en/2.0/faq/troubleshooting/) * [1.11](https://docs.djangoproject.com/en/1.11/faq/troubleshooting/) * [1.10](https://docs.djangoproject.com/en/1.10/faq/troubleshooting/) * [1.9](https://docs.djangoproject.com/en/1.9/faq/troubleshooting/) * [1.8](https://docs.djangoproject.com/en/1.8/faq/troubleshooting/) - [**](#top) # Troubleshooting[¶](#troubleshooting "Link to this heading") This page contains some advice about errors and problems commonly encountered during the development of Django applications. ## Problems running `django-admin`[¶](#problems-running-django-admin "Link to this heading") ### `command not found: django-admin`[¶](#command-not-found-django-admin "Link to this heading") [django-admin](../../ref/django-admin/) should be on your system path if you installed Django via `pip`. If it’s not in your path, ensure you have your virtual environment activated and you can try running the equivalent command `python -m django`. ### macOS permissions[¶](#macos-permissions "Link to this heading") If you’re using macOS, you may see the message “permission denied” when you try to run `django-admin`. This is because, on Unix-based systems like macOS, a file must be marked as “executable” before it can be run as a program. To do this, open Terminal.app and navigate (using the `cd` command) to the directory where [django-admin](../../ref/django-admin/) is installed, then run the command `sudo chmod +x django-admin`. ## Miscellaneous[¶](#miscellaneous "Link to this heading") ### I’m getting a `UnicodeDecodeError`. What am I doing wrong?[¶](#i-m-getting-a-unicodedecodeerror-what-am-i-doing-wrong "Link to this heading") This class of errors happen when a bytestring containing non-ASCII sequences is transformed into a Unicode string and the specified encoding is incorrect. The output generally looks like this: ``` UnicodeDecodeError: 'ascii' codec can't decode byte 0x?? in position ?: ordinal not in range(128) ``` The resolution mostly depends on the context, however here are two common pitfalls producing this error: * Your system locale may be a default ASCII locale, like the “C” locale on UNIX-like systems (can be checked by the `locale` command). If it’s the case, please refer to your system documentation to learn how you can change this to a UTF-8 locale. Related resources: * [Unicode in Django](../../ref/unicode/) * [**Back to Top](#top) ## Additional Information ### Support Django! * [Multi donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Troubleshooting](#) * [Problems running `django-admin`](#problems-running-django-admin) * [`command not found: django-admin`](#command-not-found-django-admin) * [macOS permissions](#macos-permissions) * [Miscellaneous](#miscellaneous) * [I’m getting a `UnicodeDecodeError`. What am I doing wrong?](#i-m-getting-a-unicodedecodeerror-what-am-i-doing-wrong) ---- url: https://docs.djangoproject.com/en/6.1/ref/contrib/gis/model-api/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/gis/model-api/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/contrib/gis/model-api/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/contrib/gis/model-api/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/contrib/gis/model-api/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/contrib/gis/model-api/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/contrib/gis/model-api/) - [it](https://docs.djangoproject.com/it/6.1/ref/contrib/gis/model-api/) - [id](https://docs.djangoproject.com/id/6.1/ref/contrib/gis/model-api/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/contrib/gis/model-api/) - [es](https://docs.djangoproject.com/es/6.1/ref/contrib/gis/model-api/) - [el](https://docs.djangoproject.com/el/6.1/ref/contrib/gis/model-api/) * * [dev](https://docs.djangoproject.com/en/dev/ref/contrib/gis/model-api/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/contrib/gis/model-api/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/contrib/gis/model-api/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/contrib/gis/model-api/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/contrib/gis/model-api/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/contrib/gis/model-api/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/contrib/gis/model-api/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/contrib/gis/model-api/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/contrib/gis/model-api/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/contrib/gis/model-api/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/contrib/gis/model-api/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/contrib/gis/model-api/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/contrib/gis/model-api/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/contrib/gis/model-api/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/contrib/gis/model-api/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/contrib/gis/model-api/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/contrib/gis/model-api/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/contrib/gis/model-api/) - [**](#top) # GeoDjango Model API[¶](#module-django.contrib.gis.db.models "Link to this heading") This document explores the details of the GeoDjango Model API. Throughout this section, we’ll be using the following geographic model of a [ZIP code](https://en.wikipedia.org/wiki/ZIP_code) and of a [Digital Elevation Model](https://en.wikipedia.org/wiki/Digital_elevation_model) as our examples: ``` from django.contrib.gis.db import models class Zipcode(models.Model): code = models.CharField(max_length=5) poly = models.PolygonField() class Elevation(models.Model): name = models.CharField(max_length=100) rast = models.RasterField() ``` ## Spatial Field Types[¶](#spatial-field-types "Link to this heading") Spatial fields consist of a series of geometry field types and one raster field type. Each of the geometry field types correspond to the OpenGIS Simple Features specification [\[1\]](#fnogc). There is no such standard for raster data. ### `GeometryField`[¶](#geometryfield "Link to this heading") * *class *GeometryField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L249)[¶](#django.contrib.gis.db.models.GeometryField "Link to this definition") The base class for geometry fields. ### `PointField`[¶](#pointfield "Link to this heading") * *class *PointField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L362)[¶](#django.contrib.gis.db.models.PointField "Link to this definition") Stores a [`Point`](../geos/#django.contrib.gis.geos.Point "django.contrib.gis.geos.Point"). ### `LineStringField`[¶](#linestringfield "Link to this heading") * *class *LineStringField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L369)[¶](#django.contrib.gis.db.models.LineStringField "Link to this definition") Stores a [`LineString`](../geos/#django.contrib.gis.geos.LineString "django.contrib.gis.geos.LineString"). ### `PolygonField`[¶](#polygonfield "Link to this heading") * *class *PolygonField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L376)[¶](#django.contrib.gis.db.models.PolygonField "Link to this definition") Stores a [`Polygon`](../geos/#django.contrib.gis.geos.Polygon "django.contrib.gis.geos.Polygon"). ### `MultiPointField`[¶](#multipointfield "Link to this heading") * *class *MultiPointField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L383)[¶](#django.contrib.gis.db.models.MultiPointField "Link to this definition") Stores a [`MultiPoint`](../geos/#django.contrib.gis.geos.MultiPoint "django.contrib.gis.geos.MultiPoint"). ### `MultiLineStringField`[¶](#multilinestringfield "Link to this heading") * *class *MultiLineStringField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L390)[¶](#django.contrib.gis.db.models.MultiLineStringField "Link to this definition") Stores a [`MultiLineString`](../geos/#django.contrib.gis.geos.MultiLineString "django.contrib.gis.geos.MultiLineString"). ### `MultiPolygonField`[¶](#multipolygonfield "Link to this heading") * *class *MultiPolygonField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L397)[¶](#django.contrib.gis.db.models.MultiPolygonField "Link to this definition") Stores a [`MultiPolygon`](../geos/#django.contrib.gis.geos.MultiPolygon "django.contrib.gis.geos.MultiPolygon"). ### `GeometryCollectionField`[¶](#geometrycollectionfield "Link to this heading") * *class *GeometryCollectionField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L404)[¶](#django.contrib.gis.db.models.GeometryCollectionField "Link to this definition") Stores a [`GeometryCollection`](../geos/#django.contrib.gis.geos.GeometryCollection "django.contrib.gis.geos.GeometryCollection"). ### `RasterField`[¶](#rasterfield "Link to this heading") * *class *RasterField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/db/models/fields.py#L424)[¶](#django.contrib.gis.db.models.RasterField "Link to this definition") Stores a [`GDALRaster`](../gdal/#django.contrib.gis.gdal.GDALRaster "django.contrib.gis.gdal.GDALRaster"). `RasterField` is currently only implemented for the PostGIS backend. ## Spatial Field Options[¶](#spatial-field-options "Link to this heading") In addition to the regular [Field options](../../../models/fields/#common-model-field-options) available for Django model fields, spatial fields have the following additional options. All are optional. ### `srid`[¶](#srid "Link to this heading") * BaseSpatialField.srid[¶](#django.contrib.gis.db.models.BaseSpatialField.srid "Link to this definition") Sets the SRID [\[2\]](#fnogcsrid) (Spatial Reference System Identity) of the geometry field to the given value. Defaults to 4326 (also known as [WGS84](https://en.wikipedia.org/wiki/WGS84), units are in degrees of longitude and latitude). Setting the SRID to `-1` disables automatic SRID transformations when saving geometries. The assigned geometry’s SRID is set to `-1`, discarding any explicit SRID it had. #### Selecting an SRID[¶](#selecting-an-srid "Link to this heading") Choosing an appropriate SRID for your model is an important decision that the developer should consider carefully. The SRID is an integer specifier that corresponds to the projection system that will be used to interpret the data in the spatial database. [\[3\]](#fnsrid) Projection systems give the context to the coordinates that specify a location. Although the details of [geodesy](https://en.wikipedia.org/wiki/Geodesy) are beyond the scope of this documentation, the general problem is that the earth is spherical and representations of the earth (e.g., paper maps, web maps) are not. Most people are familiar with using latitude and longitude to reference a location on the earth’s surface. However, latitude and longitude are angles, not distances. In other words, while the shortest path between two points on a flat surface is a straight line, the shortest path between two points on a curved surface (such as the earth) is an *arc* of a [great circle](https://en.wikipedia.org/wiki/Great_circle). [\[4\]](#fnthematic) Thus, additional computation is required to obtain distances in planar units (e.g., kilometers and miles). Using a geographic coordinate system may introduce complications for the developer later on. For example, SpatiaLite does not have the capability to perform distance calculations between geometries using geographic coordinate systems, e.g. constructing a query to find all points within 5 miles of a county boundary stored as WGS84. [\[5\]](#fndist) Portions of the earth’s surface may projected onto a two-dimensional, or Cartesian, plane. Projected coordinate systems are especially convenient for region-specific applications, e.g., if you know that your database will only cover geometries in [North Kansas](https://spatialreference.org/ref/epsg/2796/), then you may consider using projection system specific to that region. Moreover, projected coordinate systems are defined in Cartesian units (such as meters or feet), easing distance calculations. Note If you wish to perform arbitrary distance queries using non-point geometries in WGS84 in PostGIS and you want decent performance, enable the [`GeometryField.geography`](#django.contrib.gis.db.models.GeometryField.geography "django.contrib.gis.db.models.GeometryField.geography") keyword so that [geography database type](#geography-type) is used instead. Additional Resources: * [spatialreference.org](https://spatialreference.org/): A database of spatial reference systems. * [The State Plane Coordinate System](https://web.archive.org/web/20080302095452/http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html): A website covering the various projection systems used in the United States. Much of the U.S. spatial data encountered will be in one of these coordinate systems rather than in a geographic coordinate system such as WGS84. ### `spatial_index`[¶](#spatial-index "Link to this heading") * BaseSpatialField.spatial\_index[¶](#django.contrib.gis.db.models.BaseSpatialField.spatial_index "Link to this definition") Defaults to `True`. Creates a spatial index for the given geometry field. Note This is different from the `db_index` field option because spatial indexes are created in a different manner than regular database indexes. Specifically, spatial indexes are typically created using a variant of the R-Tree, while regular database indexes typically use B-Trees. ## Geometry Field Options[¶](#geometry-field-options "Link to this heading") There are additional options available for Geometry fields. All the following options are optional. ### `dim`[¶](#dim "Link to this heading") * GeometryField.dim[¶](#django.contrib.gis.db.models.GeometryField.dim "Link to this definition") This option may be used for customizing the coordinate dimension of the geometry field. By default, it is set to 2, for representing two-dimensional geometries. For spatial backends that support it, it may be set to 3 for three-dimensional support. Note At this time 3D support is limited to the PostGIS and SpatiaLite backends. ### `geography`[¶](#geography "Link to this heading") * GeometryField.geography[¶](#django.contrib.gis.db.models.GeometryField.geography "Link to this definition") If set to `True`, this option will create a database column of type geography, rather than geometry. Please refer to the [geography type](#geography-type) section below for more details. Note Geography support is limited to PostGIS and will force the SRID to be 4326. ### `max_geom_collections`[¶](#max-geom-collections "Link to this heading") * GeometryField.max\_geom\_collections[¶](#django.contrib.gis.db.models.GeometryField.max_geom_collections "Link to this definition") This option is forwarded to the [`form field`](../forms-api/#django.contrib.gis.forms.Field.max_geom_collections "django.contrib.gis.forms.Field.max_geom_collections") generated for this model field, bounding the geometry collection nesting depth in submitted WKB/WKT inputs before raising [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)"). Since spatial field assignments are lazy, it is also checked when values are accessed, e.g. when saving an instance, but not when read from a database. It defaults to `198`. #### Geography Type[¶](#geography-type "Link to this heading") The geography type provides native support for spatial features represented with geographic coordinates (e.g., WGS84 longitude/latitude). [\[6\]](#fngeography) Unlike the plane used by a geometry type, the geography type uses a spherical representation of its data. Distance and measurement operations performed on a geography column automatically employ great circle arc calculations and return linear units. In other words, when `ST_Distance` is called on two geographies, a value in meters is returned (as opposed to degrees if called on a geometry column in WGS84). Because geography calculations involve more mathematics, only a subset of the PostGIS spatial lookups are available for the geography type. Practically, this means that in addition to the [distance lookups](../geoquerysets/#distance-lookups) only the following additional [spatial lookups](../geoquerysets/#spatial-lookups) are available for geography columns: * [`bboverlaps`](../geoquerysets/#std-fieldlookup-bboverlaps) * [`coveredby`](../geoquerysets/#std-fieldlookup-coveredby) * [`covers`](../geoquerysets/#std-fieldlookup-covers) * [`intersects`](../geoquerysets/#std-fieldlookup-intersects) If you need to use a spatial lookup or aggregate that doesn’t support the geography type as input, you can use the [`Cast`](../../../models/database-functions/#django.db.models.functions.Cast "django.db.models.functions.Cast") database function to convert the geography column to a geometry type in the query: ``` from django.contrib.gis.db.models import PointField from django.db.models.functions import Cast Zipcode.objects.annotate(geom=Cast("geography_field", PointField())).filter( geom__within=poly ) ``` For more information, the PostGIS documentation contains a helpful section on determining [when to use geography data type over geometry data type](https://postgis.net/docs/using_postgis_dbmanagement.html#PostGIS_GeographyVSGeometry). Footnotes [**Back to Top](#top) ## Additional Information ### Support Django! * [Dmitry B donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [GeoDjango Model API](#) * [Spatial Field Types](#spatial-field-types) * [`GeometryField`](#geometryfield) * [`PointField`](#pointfield) * [`LineStringField`](#linestringfield) * [`PolygonField`](#polygonfield) * [`MultiPointField`](#multipointfield) * [`MultiLineStringField`](#multilinestringfield) * [`MultiPolygonField`](#multipolygonfield) * [`GeometryCollectionField`](#geometrycollectionfield) * [`RasterField`](#rasterfield) * [Spatial Field Options](#spatial-field-options) * [`srid`](#srid) * [Selecting an SRID](#selecting-an-srid) * [`spatial_index`](#spatial-index) * [Geometry Field Options](#geometry-field-options) * [`dim`](#dim) * [`geography`](#geography) * [`max_geom_collections`](#max-geom-collections) * [Geography Type](#geography-type) ---- url: https://docs.djangoproject.com/en/6.1/ref/contrib/postgres/constraints/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/postgres/constraints/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/contrib/postgres/constraints/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/contrib/postgres/constraints/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/contrib/postgres/constraints/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/contrib/postgres/constraints/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/contrib/postgres/constraints/) - [it](https://docs.djangoproject.com/it/6.1/ref/contrib/postgres/constraints/) - [id](https://docs.djangoproject.com/id/6.1/ref/contrib/postgres/constraints/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/contrib/postgres/constraints/) - [es](https://docs.djangoproject.com/es/6.1/ref/contrib/postgres/constraints/) - [el](https://docs.djangoproject.com/el/6.1/ref/contrib/postgres/constraints/) * * [dev](https://docs.djangoproject.com/en/dev/ref/contrib/postgres/constraints/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/contrib/postgres/constraints/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/contrib/postgres/constraints/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/contrib/postgres/constraints/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/contrib/postgres/constraints/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/contrib/postgres/constraints/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/contrib/postgres/constraints/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/contrib/postgres/constraints/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/contrib/postgres/constraints/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/contrib/postgres/constraints/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/constraints/) - [**](#top) # PostgreSQL specific database constraints[¶](#module-django.contrib.postgres.constraints "Link to this heading") PostgreSQL supports additional data integrity constraints available from the `django.contrib.postgres.constraints` module. They are added in the model [`Meta.constraints`](../../../models/options/#django.db.models.Options.constraints "django.db.models.Options.constraints") option. ## `ExclusionConstraint`[¶](#exclusionconstraint "Link to this heading") * *class *ExclusionConstraint(*\**, *name*, *expressions*, *index\_type=None*, *condition=None*, *deferrable=None*, *include=None*, *violation\_error\_code=None*, *violation\_error\_message=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/postgres/constraints.py#L22)[¶](#django.contrib.postgres.constraints.ExclusionConstraint "Link to this definition") Creates an exclusion constraint in the database. Internally, PostgreSQL implements exclusion constraints using indexes. The default index type is [GiST](https://www.postgresql.org/docs/current/gist.html). To use them, you need to activate the [btree\_gist extension](https://www.postgresql.org/docs/current/btree-gist.html) on PostgreSQL. You can install it using the [`BtreeGistExtension`](../operations/#django.contrib.postgres.operations.BtreeGistExtension "django.contrib.postgres.operations.BtreeGistExtension") migration operation. If you attempt to insert a new row that conflicts with an existing row, an [`IntegrityError`](../../../exceptions/#django.db.IntegrityError "django.db.IntegrityError") is raised. Similarly, when update conflicts with an existing row. Exclusion constraints are checked during the [model validation](../../../models/instances/#validating-objects). ### `name`[¶](#name "Link to this heading") * ExclusionConstraint.name[¶](#django.contrib.postgres.constraints.ExclusionConstraint.name "Link to this definition") See [`BaseConstraint.name`](../../../models/constraints/#django.db.models.BaseConstraint.name "django.db.models.BaseConstraint.name"). ### `expressions`[¶](#expressions "Link to this heading") * ExclusionConstraint.expressions[¶](#django.contrib.postgres.constraints.ExclusionConstraint.expressions "Link to this definition") An iterable of 2-tuples. The first element is an expression or string. The second element is an SQL operator represented as a string. To avoid typos, you may use [`RangeOperators`](../fields/#django.contrib.postgres.fields.RangeOperators "django.contrib.postgres.fields.RangeOperators") which maps the operators with strings. For example: ``` expressions = [ ("timespan", RangeOperators.ADJACENT_TO), (F("room"), RangeOperators.EQUAL), ] ``` Restrictions on operators. Only commutative operators can be used in exclusion constraints. The [`OpClass()`](../indexes/#django.contrib.postgres.indexes.OpClass "django.contrib.postgres.indexes.OpClass") expression can be used to specify a custom [operator class](https://www.postgresql.org/docs/current/indexes-opclass.html) for the constraint expressions. For example: ``` expressions = [ (OpClass("circle", name="circle_ops"), RangeOperators.OVERLAPS), ] ``` creates an exclusion constraint on `circle` using `circle_ops`. ### `index_type`[¶](#index-type "Link to this heading") * ExclusionConstraint.index\_type[¶](#django.contrib.postgres.constraints.ExclusionConstraint.index_type "Link to this definition") The index type of the constraint. Accepted values are `GiST`, `Hash`, or `SPGiST`. Matching is case insensitive. If not provided, the default index type is `GIST`. Changed in Django 6.1: Support for exclusion constraints using Hash indexes was added. ### `condition`[¶](#condition "Link to this heading") * ExclusionConstraint.condition[¶](#django.contrib.postgres.constraints.ExclusionConstraint.condition "Link to this definition") A [`Q`](../../../models/querysets/#django.db.models.Q "django.db.models.Q") object that specifies the condition to restrict a constraint to a subset of rows. For example, `condition=Q(cancelled=False)`. These conditions have the same database restrictions as [`django.db.models.Index.condition`](../../../models/indexes/#django.db.models.Index.condition "django.db.models.Index.condition"). ### `deferrable`[¶](#deferrable "Link to this heading") * ExclusionConstraint.deferrable[¶](#django.contrib.postgres.constraints.ExclusionConstraint.deferrable "Link to this definition") Set this parameter to create a deferrable exclusion constraint. Accepted values are `Deferrable.DEFERRED` or `Deferrable.IMMEDIATE`. For example: ``` from django.contrib.postgres.constraints import ExclusionConstraint from django.contrib.postgres.fields import RangeOperators from django.db.models import Deferrable ExclusionConstraint( name="exclude_overlapping_deferred", expressions=[ ("timespan", RangeOperators.OVERLAPS), ], deferrable=Deferrable.DEFERRED, ) ``` By default constraints are not deferred. A deferred constraint will not be enforced until the end of the transaction. An immediate constraint will be enforced immediately after every command. Warning Deferred exclusion constraints may lead to a [performance penalty](https://www.postgresql.org/docs/current/sql-createtable.html#id-1.9.3.85.9.4). ### `include`[¶](#include "Link to this heading") * ExclusionConstraint.include[¶](#django.contrib.postgres.constraints.ExclusionConstraint.include "Link to this definition") A list or tuple of the names of the fields to be included in the covering exclusion constraint as non-key columns. This allows index-only scans to be used for queries that select only included fields ([`include`](#django.contrib.postgres.constraints.ExclusionConstraint.include "django.contrib.postgres.constraints.ExclusionConstraint.include")) and filter only by indexed fields ([`expressions`](#django.contrib.postgres.constraints.ExclusionConstraint.expressions "django.contrib.postgres.constraints.ExclusionConstraint.expressions")). `include` is supported for GiST and SP-GiST indexes. ### `violation_error_code`[¶](#violation-error-code "Link to this heading") * ExclusionConstraint.violation\_error\_code[¶](#django.contrib.postgres.constraints.ExclusionConstraint.violation_error_code "Link to this definition") The error code used when `ValidationError` is raised during [model validation](../../../models/instances/#validating-objects). Defaults to `None`. ### `violation_error_message`[¶](#violation-error-message "Link to this heading") The error message used when `ValidationError` is raised during [model validation](../../../models/instances/#validating-objects). Defaults to [`BaseConstraint.violation_error_message`](../../../models/constraints/#django.db.models.BaseConstraint.violation_error_message "django.db.models.BaseConstraint.violation_error_message"). ### Examples[¶](#examples "Link to this heading") The following example restricts overlapping reservations in the same room, not taking canceled reservations into account: ``` from django.contrib.postgres.constraints import ExclusionConstraint from django.contrib.postgres.fields import DateTimeRangeField, RangeOperators from django.db import models from django.db.models import Q class Room(models.Model): number = models.IntegerField() class Reservation(models.Model): room = models.ForeignKey("Room", on_delete=models.CASCADE) timespan = DateTimeRangeField() cancelled = models.BooleanField(default=False) class Meta: constraints = [ ExclusionConstraint( name="exclude_overlapping_reservations", expressions=[ ("timespan", RangeOperators.OVERLAPS), ("room", RangeOperators.EQUAL), ], condition=Q(cancelled=False), ), ] ``` In case your model defines a range using two fields, instead of the native PostgreSQL range types, you should write an expression that uses the equivalent function (e.g. `TsTzRange()`), and use the delimiters for the field. Most often, the delimiters will be `'[)'`, meaning that the lower bound is inclusive and the upper bound is exclusive. You may use the [`RangeBoundary`](../fields/#django.contrib.postgres.fields.RangeBoundary "django.contrib.postgres.fields.RangeBoundary") that provides an expression mapping for the [range boundaries](https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-INCLUSIVITY). For example: ``` from django.contrib.postgres.constraints import ExclusionConstraint from django.contrib.postgres.fields import ( DateTimeRangeField, RangeBoundary, RangeOperators, ) from django.db import models from django.db.models import Func, Q class TsTzRange(Func): function = "TSTZRANGE" output_field = DateTimeRangeField() class Reservation(models.Model): room = models.ForeignKey("Room", on_delete=models.CASCADE) start = models.DateTimeField() end = models.DateTimeField() cancelled = models.BooleanField(default=False) class Meta: constraints = [ ExclusionConstraint( name="exclude_overlapping_reservations", expressions=[ ( TsTzRange("start", "end", RangeBoundary()), RangeOperators.OVERLAPS, ), ("room", RangeOperators.EQUAL), ], condition=Q(cancelled=False), ), ] ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [yee donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [PostgreSQL specific database constraints](#) * [`ExclusionConstraint`](#exclusionconstraint) * [`name`](#name) * [`expressions`](#expressions) * [`index_type`](#index-type) * [`condition`](#condition) * [`deferrable`](#deferrable) * [`include`](#include) * [`violation_error_code`](#violation-error-code) * [`violation_error_message`](#violation-error-message) * [Examples](#examples) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.5.4/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.5.4/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.5.4/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.5.4/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.5.4/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.5.4/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.5.4/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.5.4/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.5.4/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.5.4/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.5.4/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.5.4/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.5.4/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.5.4/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.5.4/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.5.4/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.5.4/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.5.4/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.5.4/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.5.4/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.5.4/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.5.4/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.5.4/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.5.4/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.5.4/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.5.4/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.5.4/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.5.4/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.5.4/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.5.4/) - [**](#top) # Django 1.5.4 release notes[¶](#django-1-5-4-release-notes "Link to this heading") *September 14, 2013* This is Django 1.5.4, the fourth release in the Django 1.5 series. It addresses two security issues and one bug. ## Denial-of-service via password hashers[¶](#denial-of-service-via-password-hashers "Link to this heading") In previous versions of Django, no limit was imposed on the plaintext length of a password. This allowed a denial-of-service attack through submission of bogus but extremely large passwords, tying up server resources performing the (expensive, and increasingly expensive with the length of the password) calculation of the corresponding hash. As of 1.5.4, Django’s authentication framework imposes a 4096-byte limit on passwords, and will fail authentication with any submitted password of greater length. ## Corrected usage of [`sensitive_post_parameters()`](../../howto/error-reporting/#django.views.decorators.debug.sensitive_post_parameters "django.views.decorators.debug.sensitive_post_parameters") in [`django.contrib.auth`](../../topics/auth/#module-django.contrib.auth "django.contrib.auth: Django's authentication framework.")’s admin[¶](#corrected-usage-of-sensitive-post-parameters-in-django-contrib-auths-admin "Link to this heading") The decoration of the `add_view` and `user_change_password` user admin views with [`sensitive_post_parameters()`](../../howto/error-reporting/#django.views.decorators.debug.sensitive_post_parameters "django.views.decorators.debug.sensitive_post_parameters") did not include [`method_decorator()`](../../ref/utils/#django.utils.decorators.method_decorator "django.utils.decorators.method_decorator") (required since the views are methods) resulting in the decorator not being properly applied. This usage has been fixed and [`sensitive_post_parameters()`](../../howto/error-reporting/#django.views.decorators.debug.sensitive_post_parameters "django.views.decorators.debug.sensitive_post_parameters") will now throw an exception if it’s improperly used. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a bug that prevented a `QuerySet` that uses [`prefetch_related()`](../../ref/models/querysets/#django.db.models.query.QuerySet.prefetch_related "django.db.models.query.QuerySet.prefetch_related") from being pickled and unpickled more than once (the second pickling attempt raised an exception) (#21102). [**Back to Top](#top) ## Additional Information ### Support Django! * [Kodi Addons donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.5.4 release notes](#) * [Denial-of-service via password hashers](#denial-of-service-via-password-hashers) * [Corrected usage of `sensitive_post_parameters()` in `django.contrib.auth`’s admin](#corrected-usage-of-sensitive-post-parameters-in-django-contrib-auths-admin) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.7.3/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.7.3/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.7.3/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.7.3/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.7.3/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.7.3/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.7.3/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.7.3/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.7.3/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.7.3/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.7.3/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.7.3/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.7.3/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.7.3/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.7.3/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.7.3/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.7.3/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.7.3/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.7.3/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.7.3/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.7.3/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.7.3/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.7.3/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.7.3/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.7.3/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.7.3/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.7.3/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.7.3/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.7.3/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.7.3/) - [**](#top) # Django 1.7.3 release notes[¶](#django-1-7-3-release-notes "Link to this heading") *January 13, 2015* Django 1.7.3 fixes several security issues and bugs in 1.7.2. ## Bugfixes[¶](#bugfixes "Link to this heading") * The default iteration count for the PBKDF2 password hasher has been increased by 25%. This part of the normal major release process was inadvertently omitted in 1.7. This backwards compatible change will not affect users who have subclassed `django.contrib.auth.hashers.PBKDF2PasswordHasher` to change the default value. * Fixed a crash in the CSRF middleware when handling non-ASCII referer header ([#23815](https://code.djangoproject.com/ticket/23815)). * Fixed a crash in the `django.contrib.auth.redirect_to_login` view when passing a `reverse_lazy()` result on Python 3 ([#24097](https://code.djangoproject.com/ticket/24097)). * Added correct formats for Greek (`el`) ([#23967](https://code.djangoproject.com/ticket/23967)). * Fixed a migration crash when unapplying a migration where multiple operations interact with the same model ([#24110](https://code.djangoproject.com/ticket/24110)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Frank Wiles donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.7.3 release notes](#) * [WSGI header spoofing via underscore/dash conflation](#wsgi-header-spoofing-via-underscore-dash-conflation) * [Mitigated possible XSS attack via user-supplied redirect URLs](#mitigated-possible-xss-attack-via-user-supplied-redirect-urls) * [Denial-of-service attack against `django.views.static.serve`](#denial-of-service-attack-against-django-views-static-serve) * [Database denial-of-service with `ModelMultipleChoiceField`](#database-denial-of-service-with-modelmultiplechoicefield) ---- url: https://docs.djangoproject.com/en/6.1/releases/2.2.4/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/2.2.4/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/2.2.4/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/2.2.4/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/2.2.4/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/2.2.4/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/2.2.4/) - [it](https://docs.djangoproject.com/it/6.1/releases/2.2.4/) - [id](https://docs.djangoproject.com/id/6.1/releases/2.2.4/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/2.2.4/) - [es](https://docs.djangoproject.com/es/6.1/releases/2.2.4/) - [el](https://docs.djangoproject.com/el/6.1/releases/2.2.4/) * * [dev](https://docs.djangoproject.com/en/dev/releases/2.2.4/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/2.2.4/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/2.2.4/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/2.2.4/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/2.2.4/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/2.2.4/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/2.2.4/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/2.2.4/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/2.2.4/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/2.2.4/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/2.2.4/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/2.2.4/) - [**](#top) # Django 2.2.4 release notes[¶](#django-2-2-4-release-notes "Link to this heading") *August 1, 2019* Django 2.2.4 fixes security issues and several bugs in 2.2.3. ## CVE-2019-14232: Denial-of-service possibility in `django.utils.text.Truncator`[¶](#cve-2019-14232-denial-of-service-possibility-in-django-utils-text-truncator "Link to this heading") If `django.utils.text.Truncator`’s `chars()` and `words()` methods were passed the `html=True` argument, they were extremely slow to evaluate certain inputs due to a catastrophic backtracking vulnerability in a regular expression. The `chars()` and `words()` methods are used to implement the [`truncatechars_html`](../../ref/templates/builtins/#std-templatefilter-truncatechars_html) and [`truncatewords_html`](../../ref/templates/builtins/#std-templatefilter-truncatewords_html) template filters, which were thus vulnerable. The regular expressions used by `Truncator` have been simplified in order to avoid potential backtracking issues. As a consequence, trailing punctuation may now at times be included in the truncated output. ## CVE-2019-14233: Denial-of-service possibility in `strip_tags()`[¶](#cve-2019-14233-denial-of-service-possibility-in-strip-tags "Link to this heading") Due to the behavior of the underlying `HTMLParser`, [`django.utils.html.strip_tags()`](../../ref/utils/#django.utils.html.strip_tags "django.utils.html.strip_tags") would be extremely slow to evaluate certain inputs containing large sequences of nested incomplete HTML entities. The `strip_tags()` method is used to implement the corresponding [`striptags`](../../ref/templates/builtins/#std-templatefilter-striptags) template filter, which was thus also vulnerable. `strip_tags()` now avoids recursive calls to `HTMLParser` when progress removing tags, but necessarily incomplete HTML entities, stops being made. Remember that absolutely NO guarantee is provided about the results of `strip_tags()` being HTML safe. So NEVER mark safe the result of a `strip_tags()` call without escaping it first, for example with [`django.utils.html.escape()`](../../ref/utils/#django.utils.html.escape "django.utils.html.escape"). ## CVE-2019-14234: SQL injection possibility in key and index lookups for `JSONField`/`HStoreField`[¶](#cve-2019-14234-sql-injection-possibility-in-key-and-index-lookups-for-jsonfield-hstorefield "Link to this heading") [`Key and index lookups`](../../topics/db/queries/#std-fieldlookup-jsonfield.key) for `django.contrib.postgres.fields.JSONField` and [`key lookups`](../../ref/contrib/postgres/fields/#std-fieldlookup-hstorefield.key) for [`HStoreField`](../../ref/contrib/postgres/fields/#django.contrib.postgres.fields.HStoreField "django.contrib.postgres.fields.HStoreField") were subject to SQL injection, using a suitably crafted dictionary, with dictionary expansion, as the `**kwargs` passed to `QuerySet.filter()`. ## CVE-2019-14235: Potential memory exhaustion in `django.utils.encoding.uri_to_iri()`[¶](#cve-2019-14235-potential-memory-exhaustion-in-django-utils-encoding-uri-to-iri "Link to this heading") If passed certain inputs, [`django.utils.encoding.uri_to_iri()`](../../ref/utils/#django.utils.encoding.uri_to_iri "django.utils.encoding.uri_to_iri") could lead to significant memory usage due to excessive recursion when re-percent-encoding invalid UTF-8 octet sequences. `uri_to_iri()` now avoids recursion when re-percent-encoding invalid UTF-8 octet sequences. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a regression in Django 2.2 when ordering a `QuerySet.union()`, `intersection()`, or `difference()` by a field type present more than once results in the wrong ordering being used ([#30628](https://code.djangoproject.com/ticket/30628)). * Fixed a migration crash on PostgreSQL when adding a check constraint with a `contains` lookup on [`DateRangeField`](../../ref/contrib/postgres/fields/#django.contrib.postgres.fields.DateRangeField "django.contrib.postgres.fields.DateRangeField") or [`DateTimeRangeField`](../../ref/contrib/postgres/fields/#django.contrib.postgres.fields.DateTimeRangeField "django.contrib.postgres.fields.DateTimeRangeField"), if the right hand side of an expression is the same type ([#30621](https://code.djangoproject.com/ticket/30621)). * Fixed a regression in Django 2.2 where auto-reloader crashes if a file path contains null characters (`'\x00'`) ([#30506](https://code.djangoproject.com/ticket/30506)). * Fixed a regression in Django 2.2 where auto-reloader crashes if a translation directory cannot be resolved ([#30647](https://code.djangoproject.com/ticket/30647)). [**Back to Top](#top) ## Additional Information ### Support Django! * [sanyodigital.com donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 2.2.4 release notes](#) * [CVE-2019-14232: Denial-of-service possibility in `django.utils.text.Truncator`](#cve-2019-14232-denial-of-service-possibility-in-django-utils-text-truncator) * [CVE-2019-14233: Denial-of-service possibility in `strip_tags()`](#cve-2019-14233-denial-of-service-possibility-in-strip-tags) * [CVE-2019-14234: SQL injection possibility in key and index lookups for `JSONField`/`HStoreField`](#cve-2019-14234-sql-injection-possibility-in-key-and-index-lookups-for-jsonfield-hstorefield) * [CVE-2019-14235: Potential memory exhaustion in `django.utils.encoding.uri_to_iri()`](#cve-2019-14235-potential-memory-exhaustion-in-django-utils-encoding-uri-to-iri) ---- url: https://docs.djangoproject.com/en/6.1/intro/overview/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/intro/overview/) - [sv](https://docs.djangoproject.com/sv/6.1/intro/overview/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/intro/overview/) - [pl](https://docs.djangoproject.com/pl/6.1/intro/overview/) - [ko](https://docs.djangoproject.com/ko/6.1/intro/overview/) - [ja](https://docs.djangoproject.com/ja/6.1/intro/overview/) - [it](https://docs.djangoproject.com/it/6.1/intro/overview/) - [id](https://docs.djangoproject.com/id/6.1/intro/overview/) - [fr](https://docs.djangoproject.com/fr/6.1/intro/overview/) - [es](https://docs.djangoproject.com/es/6.1/intro/overview/) - [el](https://docs.djangoproject.com/el/6.1/intro/overview/) * * [dev](https://docs.djangoproject.com/en/dev/intro/overview/) * [6.0](https://docs.djangoproject.com/en/6.0/intro/overview/) * [5.2](https://docs.djangoproject.com/en/5.2/intro/overview/) * [5.1](https://docs.djangoproject.com/en/5.1/intro/overview/) * [5.0](https://docs.djangoproject.com/en/5.0/intro/overview/) * [4.2](https://docs.djangoproject.com/en/4.2/intro/overview/) * [4.1](https://docs.djangoproject.com/en/4.1/intro/overview/) * [4.0](https://docs.djangoproject.com/en/4.0/intro/overview/) * [3.2](https://docs.djangoproject.com/en/3.2/intro/overview/) * [3.1](https://docs.djangoproject.com/en/3.1/intro/overview/) * [3.0](https://docs.djangoproject.com/en/3.0/intro/overview/) * [2.2](https://docs.djangoproject.com/en/2.2/intro/overview/) * [2.1](https://docs.djangoproject.com/en/2.1/intro/overview/) * [2.0](https://docs.djangoproject.com/en/2.0/intro/overview/) * [1.11](https://docs.djangoproject.com/en/1.11/intro/overview/) * [1.10](https://docs.djangoproject.com/en/1.10/intro/overview/) * [1.9](https://docs.djangoproject.com/en/1.9/intro/overview/) * [1.8](https://docs.djangoproject.com/en/1.8/intro/overview/) - [**](#top) # Django at a glance[¶](#django-at-a-glance "Link to this heading") Because Django was developed in a fast-paced newsroom environment, it was designed to make common web development tasks fast and easy. Here’s an informal overview of how to write a database-driven web app with Django. The goal of this document is to give you enough technical specifics to understand how Django works, but this isn’t intended to be a tutorial or reference – but we’ve got both! When you’re ready to start a project, you can [start with the tutorial](../tutorial01/) or [dive right into more detailed documentation](../../topics/). ## Design your model[¶](#design-your-model "Link to this heading") Although you can use Django without a database, it comes with an [object-relational mapper](https://en.wikipedia.org/wiki/Object-relational_mapping) in which you describe your database layout in Python code. The [data-model syntax](../../topics/db/models/) offers many rich ways of representing your models – so far, it’s been solving many years’ worth of database-schema problems. Here’s a quick example: `news/models.py`[¶](#id1 "Link to this code")** ``` from django.db import models class Reporter(models.Model): full_name = models.CharField(max_length=70) def __str__(self): return self.full_name class Article(models.Model): pub_date = models.DateField() headline = models.CharField(max_length=200) content = models.TextField() reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE) def __str__(self): return self.headline ``` ## Install it[¶](#install-it "Link to this heading") Next, run the Django command-line utilities to create the database tables automatically: /  ``` $ python manage.py makemigrations $ python manage.py migrate ``` ** ``` ...\> py manage.py makemigrations ...\> py manage.py migrate ``` ** The [`makemigrations`](../../ref/django-admin/#django-admin-makemigrations) command looks at all your available models and creates migrations for whichever tables don’t already exist. [`migrate`](../../ref/django-admin/#django-admin-migrate) runs the migrations and creates tables in your database, as well as optionally providing [much richer schema control](../../topics/migrations/). ## Enjoy the free API[¶](#enjoy-the-free-api "Link to this heading") With that, you’ve got a free, and rich, [Python API](../../topics/db/queries/) to access your data. The API is created on the fly, no code generation necessary: ``` # Import the models we created from our "news" app >>> from news.models import Article, Reporter # No reporters are in the system yet. >>> Reporter.objects.all() # Create a new Reporter. >>> r = Reporter(full_name="John Smith") # Save the object into the database. You have to call save() explicitly. >>> r.save() # Now it has an ID. >>> r.id 1 # Now the new reporter is in the database. >>> Reporter.objects.all() ]> # Fields are represented as attributes on the Python object. >>> r.full_name 'John Smith' # Django provides a rich database lookup API. >>> Reporter.objects.get(id=1) >>> Reporter.objects.get(full_name__startswith="John") >>> Reporter.objects.get(full_name__contains="mith") >>> Reporter.objects.get(id=2) Traceback (most recent call last): ... DoesNotExist: Reporter matching query does not exist. # Create an article. >>> from datetime import date >>> a = Article( ... pub_date=date.today(), headline="Django is cool", content="Yeah.", reporter=r ... ) >>> a.save() # Now the article is in the database. >>> Article.objects.all() ]> # Article objects get API access to related Reporter objects. >>> r = a.reporter >>> r.full_name 'John Smith' # And vice versa: Reporter objects get API access to Article objects. >>> r.article_set.all() ]> # The API follows relationships as far as you need, performing efficient # JOINs for you behind the scenes. # This finds all articles by a reporter whose name starts with "John". >>> Article.objects.filter(reporter__full_name__startswith="John") ]> # Change an object by altering its attributes and calling save(). >>> r.full_name = "Billy Goat" >>> r.save() # Delete an object with delete(). >>> r.delete() ``` ## A dynamic admin interface: it’s not just scaffolding – it’s the whole house[¶](#a-dynamic-admin-interface-it-s-not-just-scaffolding-it-s-the-whole-house "Link to this heading") Once your models are defined, Django can automatically create a professional, production ready [administrative interface](../../ref/contrib/admin/) – a website that lets authenticated users add, change and delete objects. The only step required is to register your model in the admin site: `news/models.py`[¶](#id2 "Link to this code")** ``` from django.db import models class Article(models.Model): pub_date = models.DateField() headline = models.CharField(max_length=200) content = models.TextField() reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE) ``` `news/admin.py`[¶](#id3 "Link to this code")** ``` from django.contrib import admin from . import models admin.site.register(models.Article) ``` The philosophy here is that your site is edited by a staff, or a client, or maybe just you – and you don’t want to have to deal with creating backend interfaces only to manage content. One typical workflow in creating Django apps is to create models and get the admin sites up and running as fast as possible, so your staff (or clients) can start populating data. Then, develop the way data is presented to the public. ## Design your URLs[¶](#design-your-urls "Link to this heading") A clean, elegant URL scheme is an important detail in a high-quality web application. Django encourages beautiful URL design and doesn’t put any cruft in URLs, like `.php` or `.asp`. To design URLs for an app, you create a Python module called a [URLconf](../../topics/http/urls/). A table of contents for your app, it contains a mapping between URL patterns and Python callback functions. URLconfs also serve to decouple URLs from Python code. Here’s what a URLconf might look like for the `Reporter`/`Article` example above: `news/urls.py`[¶](#id4 "Link to this code")** ``` from django.urls import path from . import views urlpatterns = [ path("articles//", views.year_archive), path("articles///", views.month_archive), path("articles////", views.article_detail), ] ``` The code above maps URL paths to Python callback functions (“views”). The path strings use parameter tags to “capture” values from the URLs. When a user requests a page, Django runs through each path, in order, and stops at the first one that matches the requested URL. (If none of them matches, Django calls a special-case 404 view.) This is blazingly fast, because the paths are compiled into regular expressions at load time. Once one of the URL patterns matches, Django calls the given view, which is a Python function. Each view gets passed a request object – which contains request metadata – and the values captured in the pattern. For example, if a user requested the URL “/articles/2005/05/39323/”, Django would call the function `news.views.article_detail(request, year=2005, month=5, pk=39323)`. ## Write your views[¶](#write-your-views "Link to this heading") Each view is responsible for doing one of two things: Returning an [`HttpResponse`](../../ref/request-response/#django.http.HttpResponse "django.http.HttpResponse") object containing the content for the requested page, or raising an exception such as [`Http404`](../../topics/http/views/#django.http.Http404 "django.http.Http404"). The rest is up to you. Generally, a view retrieves data according to the parameters, loads a template and renders the template with the retrieved data. Here’s an example view for `year_archive` from above: `news/views.py`[¶](#id5 "Link to this code")** ``` from django.shortcuts import render from .models import Article def year_archive(request, year): a_list = Article.objects.filter(pub_date__year=year) context = {"year": year, "article_list": a_list} return render(request, "news/year_archive.html", context) ``` This example uses Django’s [template system](../../topics/templates/), which has several powerful features but strives to stay simple enough for non-programmers to use. ## Design your templates[¶](#design-your-templates "Link to this heading") The code above loads the `news/year_archive.html` template. Django has a template search path, which allows you to minimize redundancy among templates. In your Django settings, you specify a list of directories to check for templates with [`DIRS`](../../ref/settings/#std-setting-TEMPLATES-DIRS). If a template doesn’t exist in the first directory, it checks the second, and so on. Let’s say the `news/year_archive.html` template was found. Here’s what that might look like: `news/templates/news/year_archive.html`[¶](#id6 "Link to this code")** ``` {% extends "base.html" %} {% block title %}Articles for {{ year }}{% endblock %} {% block content %}

Articles for {{ year }}

{% for article in article_list %}

{{ article.headline }}

By {{ article.reporter.full_name }}

Published {{ article.pub_date|date:"F j, Y" }}

{% endfor %} {% endblock %} ``` Variables are surrounded by double-curly braces. `{{ article.headline }}` means “Output the value of the article’s headline attribute.” But dots aren’t used only for attribute lookup. They also can do dictionary-key lookup, index lookup and function calls. Note `{{ article.pub_date|date:"F j, Y" }}` uses a Unix-style “pipe” (the “|” character). This is called a template filter, and it’s a way to filter the value of a variable. In this case, the date filter formats a Python datetime object in the given format (as found in PHP’s date function). You can chain together as many filters as you’d like. You can write [custom template filters](../../howto/custom-template-tags/#howto-writing-custom-template-filters). You can write [custom template tags](../../howto/custom-template-tags/), which run custom Python code behind the scenes. Finally, Django uses the concept of “template inheritance”. That’s what the `{% extends "base.html" %}` does. It means “First load the template called ‘base’, which has defined a bunch of blocks, and fill the blocks with the following blocks.” In short, that lets you dramatically cut down on redundancy in templates: each template has to define only what’s unique to that template. Here’s what the “base.html” template, including the use of [static files](../../howto/static-files/), might look like: `templates/base.html`[¶](#id7 "Link to this code")** ``` {% load static %} {% block title %}{% endblock %} Logo {% block content %}{% endblock %} ``` Simplistically, it defines the look-and-feel of the site (with the site’s logo), and provides “holes” for child templates to fill. This means that a site redesign can be done by changing a single file – the base template. It also lets you create multiple versions of a site, with different base templates, while reusing child templates. Django’s creators have used this technique to create strikingly different mobile versions of sites by only creating a new base template. Note that you don’t have to use Django’s template system if you prefer another system. While Django’s template system is particularly well-integrated with Django’s model layer, nothing forces you to use it. For that matter, you don’t have to use Django’s database API, either. You can use another database abstraction layer, you can read XML files, you can read files off disk, or anything you want. Each piece of Django – models, views, templates – is decoupled from the next. ## This is just the surface[¶](#this-is-just-the-surface "Link to this heading") This has been only a quick overview of Django’s functionality. Some more useful features: * A [caching framework](../../topics/cache/) that integrates with memcached or other backends. * A [syndication framework](../../ref/contrib/syndication/) that lets you create RSS and Atom feeds by writing a small Python class. * More attractive automatically-generated admin features – this overview barely scratched the surface. The next steps are for you to [download Django](https://www.djangoproject.com/download/), read [the tutorial](../tutorial01/) and join [the community](https://www.djangoproject.com/community/). Thanks for your interest! [**Back to Top](#top) ## Additional Information ### Support Django! * [Leukeleu donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django at a glance](#) * [Design your model](#design-your-model) * [Install it](#install-it) * [Enjoy the free API](#enjoy-the-free-api) * [A dynamic admin interface: it’s not just scaffolding – it’s the whole house](#a-dynamic-admin-interface-it-s-not-just-scaffolding-it-s-the-whole-house) * [Design your URLs](#design-your-urls) * [Write your views](#write-your-views) * [Design your templates](#design-your-templates) * [This is just the surface](#this-is-just-the-surface) ---- url: https://docs.djangoproject.com/en/6.1/ref/validators/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/validators/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/validators/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/validators/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/validators/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/validators/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/validators/) - [it](https://docs.djangoproject.com/it/6.1/ref/validators/) - [id](https://docs.djangoproject.com/id/6.1/ref/validators/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/validators/) - [es](https://docs.djangoproject.com/es/6.1/ref/validators/) - [el](https://docs.djangoproject.com/el/6.1/ref/validators/) * * [dev](https://docs.djangoproject.com/en/dev/ref/validators/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/validators/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/validators/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/validators/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/validators/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/validators/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/validators/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/validators/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/validators/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/validators/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/validators/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/validators/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/validators/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/validators/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/validators/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/validators/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/validators/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/validators/) - [**](#top) # Validators[¶](#module-django.core.validators "Link to this heading") ## Writing validators[¶](#writing-validators "Link to this heading") A validator is a callable that takes a value and raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if it doesn’t meet some criteria. Validators can be useful for reusing validation logic between different types of fields. For example, here’s a validator that only allows even numbers: ``` from django.core.exceptions import ValidationError from django.utils.translation import gettext_lazy as _ def validate_even(value): if value % 2 != 0: raise ValidationError( _("%(value)s is not an even number"), params={"value": value}, ) ``` You can add this to a model field via the field’s [`validators`](../models/fields/#django.db.models.Field.validators "django.db.models.Field.validators") argument: ``` from django.db import models class MyModel(models.Model): even_field = models.IntegerField(validators=[validate_even]) ``` Because values are converted to Python before validators are run, you can even use the same validator with forms: ``` from django import forms class MyForm(forms.Form): even_field = forms.IntegerField(validators=[validate_even]) ``` You can also use a class with a `__call__()` method for more complex or configurable validators. [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator"), for example, uses this technique. If a class-based validator is used in the [`validators`](../models/fields/#django.db.models.Field.validators "django.db.models.Field.validators") model field option, you should make sure it is [serializable by the migration framework](../../topics/migrations/#migration-serializing) by adding [deconstruct()](../../topics/migrations/#custom-deconstruct-method) and `__eq__()` methods. ## How validators are run[¶](#how-validators-are-run "Link to this heading") See the [form validation](../forms/validation/) for more information on how validators are run in forms, and [Validating objects](../models/instances/#validating-objects) for how they’re run in models. Note that validators will not be run automatically when you save a model, but if you are using a [`ModelForm`](../../topics/forms/modelforms/#django.forms.ModelForm "django.forms.ModelForm"), it will run your validators on any fields that are included in your form. See the [ModelForm documentation](../../topics/forms/modelforms/) for information on how model validation interacts with forms. ## Built-in validators[¶](#built-in-validators "Link to this heading") The [`django.core.validators`](#module-django.core.validators "django.core.validators: Validation utilities and base classes") module contains a collection of callable validators for use with model and form fields. They’re used internally but are available for use with your own fields, too. They can be used in addition to, or in lieu of custom `field.clean()` methods. ### `RegexValidator`[¶](#regexvalidator "Link to this heading") * *class *RegexValidator(*regex=None*, *message=None*, *code=None*, *inverse\_match=None*, *flags=0*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L20)[¶](#django.core.validators.RegexValidator "Link to this definition") * Parameters: * **regex** – If not `None`, overrides [`regex`](#django.core.validators.RegexValidator.regex "django.core.validators.RegexValidator.regex"). Can be a regular expression string or a pre-compiled regular expression. * **message** – If not `None`, overrides [`message`](#django.core.validators.RegexValidator.message "django.core.validators.RegexValidator.message"). * **code** – If not `None`, overrides [`code`](#django.core.validators.RegexValidator.code "django.core.validators.RegexValidator.code"). * **inverse\_match** – If not `None`, overrides [`inverse_match`](#django.core.validators.RegexValidator.inverse_match "django.core.validators.RegexValidator.inverse_match"). * **flags** – If not `None`, overrides [`flags`](#django.core.validators.RegexValidator.flags "django.core.validators.RegexValidator.flags"). In that case, [`regex`](#django.core.validators.RegexValidator.regex "django.core.validators.RegexValidator.regex") must be a regular expression string, or [`TypeError`](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") is raised. A [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") searches the provided `value` for a given regular expression with [`re.search()`](https://docs.python.org/3/library/re.html#re.search "(in Python v3.15)"). By default, raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with [`message`](#django.core.validators.RegexValidator.message "django.core.validators.RegexValidator.message") and [`code`](#django.core.validators.RegexValidator.code "django.core.validators.RegexValidator.code") if a match **is not** found. Its behavior can be inverted by setting [`inverse_match`](#django.core.validators.RegexValidator.inverse_match "django.core.validators.RegexValidator.inverse_match") to `True`, in which case the [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") is raised when a match **is** found. * regex[¶](#django.core.validators.RegexValidator.regex "Link to this definition") The regular expression pattern to search for within the provided `value`, using [`re.search()`](https://docs.python.org/3/library/re.html#re.search "(in Python v3.15)"). This may be a string or a pre-compiled regular expression created with [`re.compile()`](https://docs.python.org/3/library/re.html#re.compile "(in Python v3.15)"). Defaults to the empty string, which will be found in every possible `value`. - message[¶](#django.core.validators.RegexValidator.message "Link to this definition") The error message used by [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if validation fails. Defaults to `"Enter a valid value"`. * code[¶](#django.core.validators.RegexValidator.code "Link to this definition") The error code used by [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if validation fails. Defaults to `"invalid"`. - inverse\_match[¶](#django.core.validators.RegexValidator.inverse_match "Link to this definition") The match mode for [`regex`](#django.core.validators.RegexValidator.regex "django.core.validators.RegexValidator.regex"). Defaults to `False`. * flags[¶](#django.core.validators.RegexValidator.flags "Link to this definition") The [regex flags](https://docs.python.org/3/library/re.html#contents-of-module-re "(in Python v3.15)") used when compiling the regular expression string [`regex`](#django.core.validators.RegexValidator.regex "django.core.validators.RegexValidator.regex"). If [`regex`](#django.core.validators.RegexValidator.regex "django.core.validators.RegexValidator.regex") is a pre-compiled regular expression, and [`flags`](#django.core.validators.RegexValidator.flags "django.core.validators.RegexValidator.flags") is overridden, [`TypeError`](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") is raised. Defaults to `0`. ### `EmailValidator`[¶](#emailvalidator "Link to this heading") * *class *EmailValidator(*message=None*, *code=None*, *allowlist=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L210)[¶](#django.core.validators.EmailValidator "Link to this definition") * Parameters: * **message** – If not `None`, overrides [`message`](#django.core.validators.EmailValidator.message "django.core.validators.EmailValidator.message"). * **code** – If not `None`, overrides [`code`](#django.core.validators.EmailValidator.code "django.core.validators.EmailValidator.code"). * **allowlist** – If not `None`, overrides [`allowlist`](#django.core.validators.EmailValidator.allowlist "django.core.validators.EmailValidator.allowlist"). An [`EmailValidator`](#django.core.validators.EmailValidator "django.core.validators.EmailValidator") ensures that a value looks like an email address, and raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with [`message`](#django.core.validators.EmailValidator.message "django.core.validators.EmailValidator.message") and [`code`](#django.core.validators.EmailValidator.code "django.core.validators.EmailValidator.code") if it doesn’t. Values longer than 320 characters are always considered invalid. * message[¶](#django.core.validators.EmailValidator.message "Link to this definition") The error message used by [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if validation fails. Defaults to `"Enter a valid email address"`. - code[¶](#django.core.validators.EmailValidator.code "Link to this definition") The error code used by [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if validation fails. Defaults to `"invalid"`. * allowlist[¶](#django.core.validators.EmailValidator.allowlist "Link to this definition") Allowlist of email domains. By default, a regular expression (the `domain_regex` attribute) is used to validate whatever appears after the `@` sign. However, if that string appears in the `allowlist`, this validation is bypassed. If not provided, the default `allowlist` is `['localhost']`. Other domains that don’t contain a dot won’t pass validation, so you’d need to add them to the `allowlist` as necessary. ### `DomainNameValidator`[¶](#domainnamevalidator "Link to this heading") * *class *DomainNameValidator(*accept\_idna=True*, *message=None*, *code=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L69)[¶](#django.core.validators.DomainNameValidator "Link to this definition") A [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") subclass that ensures a value looks like a domain name. Values longer than 255 characters are always considered invalid. IP addresses are not accepted as valid domain names. In addition to the optional arguments of its parent [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") class, `DomainNameValidator` accepts an extra optional attribute: * accept\_idna[¶](#django.core.validators.DomainNameValidator.accept_idna "Link to this definition") Determines whether to accept internationalized domain names, that is, domain names that contain non-ASCII characters. Defaults to `True`. ### `URLValidator`[¶](#urlvalidator "Link to this heading") * *class *URLValidator(*schemes=None*, *regex=None*, *message=None*, *code=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L130)[¶](#django.core.validators.URLValidator "Link to this definition") A [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") subclass that ensures a value looks like a URL, and raises an error code of `'invalid'` if it doesn’t. Values longer than [`max_length`](#django.core.validators.URLValidator.max_length "django.core.validators.URLValidator.max_length") characters are always considered invalid. Loopback addresses and reserved IP spaces are considered valid. Literal IPv6 addresses ([**RFC 3986 Section 3.2.2**](https://datatracker.ietf.org/doc/html/rfc3986.html#section-3.2.2)) and Unicode domains are both supported. In addition to the optional arguments of its parent [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") class, `URLValidator` accepts an extra optional attribute: * schemes[¶](#django.core.validators.URLValidator.schemes "Link to this definition") URL/URI scheme list to validate against. If not provided, the default list is `['http', 'https', 'ftp', 'ftps']`. As a reference, the IANA website provides a full list of [valid URI schemes](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml). Warning Values starting with `file:///` will not pass validation even when the `file` scheme is provided. Valid values must contain a host. - max\_length[¶](#django.core.validators.URLValidator.max_length "Link to this definition") The maximum length of values that could be considered valid. Defaults to 2048 characters. ### `validate_email`[¶](#validate-email "Link to this heading") * validate\_email[¶](#django.core.validators.validate_email "Link to this definition") An [`EmailValidator`](#django.core.validators.EmailValidator "django.core.validators.EmailValidator") instance without any customizations. ### `validate_domain_name`[¶](#validate-domain-name "Link to this heading") * validate\_domain\_name[¶](#django.core.validators.validate_domain_name "Link to this definition") A [`DomainNameValidator`](#django.core.validators.DomainNameValidator "django.core.validators.DomainNameValidator") instance without any customizations. ### `validate_slug`[¶](#validate-slug "Link to this heading") * validate\_slug[¶](#django.core.validators.validate_slug "Link to this definition") A [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") instance that ensures a value consists of only letters, numbers, underscores or hyphens. ### `validate_unicode_slug`[¶](#validate-unicode-slug "Link to this heading") * validate\_unicode\_slug[¶](#django.core.validators.validate_unicode_slug "Link to this definition") A [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") instance that ensures a value consists of only Unicode letters, numbers, underscores, or hyphens. ### `validate_ipv4_address`[¶](#validate-ipv4-address "Link to this heading") * validate\_ipv4\_address[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L304)[¶](#django.core.validators.validate_ipv4_address "Link to this definition") A [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") instance that ensures a value looks like an IPv4 address. ### `validate_ipv6_address`[¶](#validate-ipv6-address "Link to this heading") * validate\_ipv6\_address[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L315)[¶](#django.core.validators.validate_ipv6_address "Link to this definition") Uses `django.utils.ipv6` to check the validity of an IPv6 address. ### `validate_ipv46_address`[¶](#validate-ipv46-address "Link to this heading") * validate\_ipv46\_address[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L324)[¶](#django.core.validators.validate_ipv46_address "Link to this definition") Uses both `validate_ipv4_address` and `validate_ipv6_address` to ensure a value is either a valid IPv4 or IPv6 address. ### `validate_comma_separated_integer_list`[¶](#validate-comma-separated-integer-list "Link to this heading") * validate\_comma\_separated\_integer\_list[¶](#django.core.validators.validate_comma_separated_integer_list "Link to this definition") A [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") instance that ensures a value is a comma-separated list of integers. ### `int_list_validator`[¶](#int-list-validator "Link to this heading") * int\_list\_validator(*sep=','*, *message=None*, *code='invalid'*, *allow\_negative=False*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L363)[¶](#django.core.validators.int_list_validator "Link to this definition") Returns a [`RegexValidator`](#django.core.validators.RegexValidator "django.core.validators.RegexValidator") instance that ensures a string consists of integers separated by `sep`. It allows negative integers when `allow_negative` is `True`. ### `MaxValueValidator`[¶](#maxvaluevalidator "Link to this heading") * *class *MaxValueValidator(*limit\_value*, *message=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L415)[¶](#django.core.validators.MaxValueValidator "Link to this definition") Raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with a code of `'max_value'` if `value` is greater than `limit_value`, which may be a callable. ### `MinValueValidator`[¶](#minvaluevalidator "Link to this heading") * *class *MinValueValidator(*limit\_value*, *message=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L424)[¶](#django.core.validators.MinValueValidator "Link to this definition") Raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with a code of `'min_value'` if `value` is less than `limit_value`, which may be a callable. ### `MaxLengthValidator`[¶](#maxlengthvalidator "Link to this heading") * *class *MaxLengthValidator(*limit\_value*, *message=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L489)[¶](#django.core.validators.MaxLengthValidator "Link to this definition") Raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with a code of `'max_length'` if the length of `value` is greater than `limit_value`, which may be a callable. ### `MinLengthValidator`[¶](#minlengthvalidator "Link to this heading") * *class *MinLengthValidator(*limit\_value*, *message=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L471)[¶](#django.core.validators.MinLengthValidator "Link to this definition") Raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with a code of `'min_length'` if the length of `value` is less than `limit_value`, which may be a callable. ### `DecimalValidator`[¶](#decimalvalidator "Link to this heading") * *class *DecimalValidator(*max\_digits*, *decimal\_places*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L507)[¶](#django.core.validators.DecimalValidator "Link to this definition") Raises [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with the following codes: * `'max_digits'` if the number of digits is larger than `max_digits`. * `'max_decimal_places'` if the number of decimals is larger than `decimal_places`. * `'max_whole_digits'` if the number of whole digits is larger than the difference between `max_digits` and `decimal_places`. ### `FileExtensionValidator`[¶](#fileextensionvalidator "Link to this heading") * *class *FileExtensionValidator(*allowed\_extensions*, *message*, *code*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L595)[¶](#django.core.validators.FileExtensionValidator "Link to this definition") Raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with a code of `'invalid_extension'` if the extension of `value.name` (`value` is a [`File`](../files/file/#django.core.files.File "django.core.files.File")) isn’t found in `allowed_extensions`. The extension is compared case-insensitively with `allowed_extensions`. Warning Don’t rely on validation of the file extension to determine a file’s type. Files can be renamed to have any extension no matter what data they contain. ### `validate_image_file_extension`[¶](#validate-image-file-extension "Link to this heading") * validate\_image\_file\_extension[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L649)[¶](#django.core.validators.validate_image_file_extension "Link to this definition") Uses Pillow to ensure that `value.name` (`value` is a [`File`](../files/file/#django.core.files.File "django.core.files.File")) has [a valid image extension](https://pillow.readthedocs.io/en/latest/handbook/image-file-formats.html). ### `ProhibitNullCharactersValidator`[¶](#prohibitnullcharactersvalidator "Link to this heading") * *class *ProhibitNullCharactersValidator(*message=None*, *code=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L656)[¶](#django.core.validators.ProhibitNullCharactersValidator "Link to this definition") Raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if `str(value)` contains one or more null characters (`'\x00'`). * Parameters: * **message** – If not `None`, overrides [`message`](#django.core.validators.ProhibitNullCharactersValidator.message "django.core.validators.ProhibitNullCharactersValidator.message"). * **code** – If not `None`, overrides [`code`](#django.core.validators.ProhibitNullCharactersValidator.code "django.core.validators.ProhibitNullCharactersValidator.code"). - message[¶](#django.core.validators.ProhibitNullCharactersValidator.message "Link to this definition") The error message used by [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if validation fails. Defaults to `"Null characters are not allowed."`. * code[¶](#django.core.validators.ProhibitNullCharactersValidator.code "Link to this definition") The error code used by [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if validation fails. Defaults to `"null_characters_not_allowed"`. ### `StepValueValidator`[¶](#stepvaluevalidator "Link to this heading") * *class *StepValueValidator(*limit\_value*, *message=None*, *offset=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/core/validators.py#L433)[¶](#django.core.validators.StepValueValidator "Link to this definition") Raises a [`ValidationError`](../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") with a code of `'step_size'` if `value` is not an integral multiple of `limit_value`, which can be a float, integer or decimal value or a callable. When `offset` is set, the validation occurs against `limit_value` plus `offset`. For example, for `StepValueValidator(3, offset=1.4)` valid values include `1.4`, `4.4`, `7.4`, `10.4`, and so on. [**Back to Top](#top) ## Additional Information ### Support Django! * [yedpodtrzitko donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Validators](#) * [Writing validators](#writing-validators) * [How validators are run](#how-validators-are-run) * [Built-in validators](#built-in-validators) * [`RegexValidator`](#regexvalidator) * [`EmailValidator`](#emailvalidator) * [`DomainNameValidator`](#domainnamevalidator) * [`URLValidator`](#urlvalidator) * [`validate_email`](#validate-email) * [`validate_domain_name`](#validate-domain-name) * [`validate_slug`](#validate-slug) * [`validate_unicode_slug`](#validate-unicode-slug) * [`validate_ipv4_address`](#validate-ipv4-address) * [`validate_ipv6_address`](#validate-ipv6-address) * [`validate_ipv46_address`](#validate-ipv46-address) * [`validate_comma_separated_integer_list`](#validate-comma-separated-integer-list) * [`int_list_validator`](#int-list-validator) * [`MaxValueValidator`](#maxvaluevalidator) * [`MinValueValidator`](#minvaluevalidator) * [`MaxLengthValidator`](#maxlengthvalidator) * [`MinLengthValidator`](#minlengthvalidator) * [`DecimalValidator`](#decimalvalidator) * [`FileExtensionValidator`](#fileextensionvalidator) * [`validate_image_file_extension`](#validate-image-file-extension) * [`ProhibitNullCharactersValidator`](#prohibitnullcharactersvalidator) * [`StepValueValidator`](#stepvaluevalidator) ---- url: https://docs.djangoproject.com/en/6.1/howto/delete-app/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/howto/delete-app/) - [sv](https://docs.djangoproject.com/sv/6.1/howto/delete-app/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/howto/delete-app/) - [pl](https://docs.djangoproject.com/pl/6.1/howto/delete-app/) - [ko](https://docs.djangoproject.com/ko/6.1/howto/delete-app/) - [ja](https://docs.djangoproject.com/ja/6.1/howto/delete-app/) - [it](https://docs.djangoproject.com/it/6.1/howto/delete-app/) - [id](https://docs.djangoproject.com/id/6.1/howto/delete-app/) - [fr](https://docs.djangoproject.com/fr/6.1/howto/delete-app/) - [es](https://docs.djangoproject.com/es/6.1/howto/delete-app/) - [el](https://docs.djangoproject.com/el/6.1/howto/delete-app/) * * [dev](https://docs.djangoproject.com/en/dev/howto/delete-app/) * [6.0](https://docs.djangoproject.com/en/6.0/howto/delete-app/) * [5.2](https://docs.djangoproject.com/en/5.2/howto/delete-app/) * [5.1](https://docs.djangoproject.com/en/5.1/howto/delete-app/) * [5.0](https://docs.djangoproject.com/en/5.0/howto/delete-app/) * [4.2](https://docs.djangoproject.com/en/4.2/howto/delete-app/) - [**](#top) # How to delete a Django application[¶](#how-to-delete-a-django-application "Link to this heading") Django provides the ability to group sets of features into Python packages called [applications](../../ref/applications/). When requirements change, apps may become obsolete or unnecessary. The following steps will help you delete an application safely. 1. Remove all references to the app (imports, foreign keys etc.). 2. Remove all models from the corresponding `models.py` file. 3. Create relevant migrations by running [`makemigrations`](../../ref/django-admin/#django-admin-makemigrations). This step generates a migration that deletes tables for the removed models, and any other required migration for updating relationships connected to those models. 4. [Squash](../../topics/migrations/#migration-squashing) out references to the app in other apps’ migrations. 5. Apply migrations locally, run tests, and verify the correctness of your project. 6. Deploy/release your updated Django project. 7. Remove the app from [`INSTALLED_APPS`](../../ref/settings/#std-setting-INSTALLED_APPS). 8. Finally, remove the app’s directory. [**Back to Top](#top) ## Additional Information ### Support Django! * [Jannis Leidel donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [How to delete a Django application](#) ---- url: https://docs.djangoproject.com/en/6.1/internals/contributing/writing-code/javascript/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/internals/contributing/writing-code/javascript/) - [sv](https://docs.djangoproject.com/sv/6.1/internals/contributing/writing-code/javascript/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/internals/contributing/writing-code/javascript/) - [pl](https://docs.djangoproject.com/pl/6.1/internals/contributing/writing-code/javascript/) - [ko](https://docs.djangoproject.com/ko/6.1/internals/contributing/writing-code/javascript/) - [ja](https://docs.djangoproject.com/ja/6.1/internals/contributing/writing-code/javascript/) - [it](https://docs.djangoproject.com/it/6.1/internals/contributing/writing-code/javascript/) - [id](https://docs.djangoproject.com/id/6.1/internals/contributing/writing-code/javascript/) - [fr](https://docs.djangoproject.com/fr/6.1/internals/contributing/writing-code/javascript/) - [es](https://docs.djangoproject.com/es/6.1/internals/contributing/writing-code/javascript/) - [el](https://docs.djangoproject.com/el/6.1/internals/contributing/writing-code/javascript/) * * [dev](https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/javascript/) * [6.0](https://docs.djangoproject.com/en/6.0/internals/contributing/writing-code/javascript/) * [5.2](https://docs.djangoproject.com/en/5.2/internals/contributing/writing-code/javascript/) * [5.1](https://docs.djangoproject.com/en/5.1/internals/contributing/writing-code/javascript/) * [5.0](https://docs.djangoproject.com/en/5.0/internals/contributing/writing-code/javascript/) * [4.2](https://docs.djangoproject.com/en/4.2/internals/contributing/writing-code/javascript/) * [4.1](https://docs.djangoproject.com/en/4.1/internals/contributing/writing-code/javascript/) * [4.0](https://docs.djangoproject.com/en/4.0/internals/contributing/writing-code/javascript/) * [3.2](https://docs.djangoproject.com/en/3.2/internals/contributing/writing-code/javascript/) * [3.1](https://docs.djangoproject.com/en/3.1/internals/contributing/writing-code/javascript/) * [3.0](https://docs.djangoproject.com/en/3.0/internals/contributing/writing-code/javascript/) * [2.2](https://docs.djangoproject.com/en/2.2/internals/contributing/writing-code/javascript/) * [2.1](https://docs.djangoproject.com/en/2.1/internals/contributing/writing-code/javascript/) * [2.0](https://docs.djangoproject.com/en/2.0/internals/contributing/writing-code/javascript/) * [1.11](https://docs.djangoproject.com/en/1.11/internals/contributing/writing-code/javascript/) * [1.10](https://docs.djangoproject.com/en/1.10/internals/contributing/writing-code/javascript/) * [1.9](https://docs.djangoproject.com/en/1.9/internals/contributing/writing-code/javascript/) - [**](#top) # JavaScript code[¶](#javascript-code "Link to this heading") While most of Django core is Python, the `admin` and `gis` contrib apps contain JavaScript code. Please follow these coding standards when writing JavaScript code for inclusion in Django. ## Code style[¶](#code-style "Link to this heading") * Please conform to the indentation style dictated in the `.editorconfig` file. We recommend using a text editor with [EditorConfig](https://editorconfig.org/) support to avoid indentation and whitespace issues. Most of the JavaScript files use 4 spaces for indentation, but there are some exceptions. * When naming variables, use `camelCase` instead of `underscore_case`. Different JavaScript files sometimes use a different code style. Please try to conform to the code style of each file. * Use the [Biome](https://biomejs.dev/) code linter to check your code for bugs and style errors. Biome will be run by the pre-commit hooks. We also recommended installing a Biome plugin in your text editor. * Where possible, write code that will work even if the page structure is later changed with JavaScript. For instance, when binding a click handler, use `$('body').on('click', selector, func)` instead of `$(selector).click(func)`. This makes it easier for projects to extend Django’s default behavior with JavaScript. ## JavaScript patches[¶](#javascript-patches "Link to this heading") Django’s admin system leverages the jQuery framework to increase the capabilities of the admin interface. In conjunction, there is an emphasis on admin JavaScript performance and minimizing overall admin media file size. ## JavaScript tests[¶](#javascript-tests "Link to this heading") Django’s JavaScript tests can be run in a browser or from the command line. The tests are located in a top level [js\_tests](https://github.com/django/django/blob/main/js_tests) directory. ### Writing tests[¶](#writing-tests "Link to this heading") Django’s JavaScript tests use [QUnit](https://qunitjs.com/). Here is an example test module: ``` QUnit.module('magicTricks', { beforeEach: function() { const $ = django.jQuery; $('#qunit-fixture').append(''); } }); QUnit.test('removeOnClick removes button on click', function(assert) { const $ = django.jQuery; removeOnClick('.button'); assert.equal($('.button').length, 1); $('.button').click(); assert.equal($('.button').length, 0); }); QUnit.test('copyOnClick adds button on click', function(assert) { const $ = django.jQuery; copyOnClick('.button'); assert.equal($('.button').length, 1); $('.button').click(); assert.equal($('.button').length, 2); }); ``` Please consult the `QUnit` documentation for information on the types of [assertions supported by QUnit](https://api.qunitjs.com/assert/). ### Running tests[¶](#running-tests "Link to this heading") The JavaScript tests may be run from a web browser or from the command line. #### Testing from a web browser[¶](#testing-from-a-web-browser "Link to this heading") To run the tests from a web browser, open up [js\_tests/tests.html](https://github.com/django/django/blob/main/js_tests/tests.html) in your browser. To measure code coverage when running the tests, you need to view that file over HTTP. To view code coverage: * Execute `python -m http.server` from the root directory (not from inside `js_tests`). * Open in your web browser. #### Testing from the command line[¶](#testing-from-the-command-line "Link to this heading") To run the tests from the command line, you need to have [Node.js](https://nodejs.org/) installed. After installing `Node.js`, install the JavaScript test dependencies by running the following from the root of your Django checkout: /  ``` $ npm install ``` ** ``` ...\> npm install ``` ** Then run the tests with: /  ``` $ npm test ``` ** ``` ...\> npm test ``` ** [**Back to Top](#top) ## Additional Information ### Support Django! * [Price Benowitz Accident Injury Lawyers, LLP donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [JavaScript code](#) * [Code style](#code-style) * [JavaScript patches](#javascript-patches) * [JavaScript tests](#javascript-tests) * [Writing tests](#writing-tests) * [Running tests](#running-tests) * [Testing from a web browser](#testing-from-a-web-browser) * [Testing from the command line](#testing-from-the-command-line) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.4.20/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.4.20/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.4.20/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.4.20/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.4.20/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.4.20/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.4.20/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.4.20/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.4.20/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.4.20/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.4.20/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.4.20/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.4.20/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.4.20/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.4.20/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.4.20/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.4.20/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.4.20/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.4.20/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.4.20/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.4.20/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.4.20/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.4.20/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.4.20/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.4.20/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.4.20/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.4.20/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.4.20/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.4.20/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.4.20/) - [**](#top) # Django 1.4.20 release notes[¶](#django-1-4-20-release-notes "Link to this heading") *March 18, 2015* Django 1.4.20 fixes one security issue in 1.4.19. ## Mitigated possible XSS attack via user-supplied redirect URLs[¶](#mitigated-possible-xss-attack-via-user-supplied-redirect-urls "Link to this heading") Django relies on user input in some cases (e.g. `django.contrib.auth.views.login()` and [i18n](../../topics/i18n/)) to redirect the user to an “on success” URL. The security checks for these redirects (namely `django.utils.http.is_safe_url()`) accepted URLs with leading control characters and so considered URLs like `\x08javascript:...` safe. This issue doesn’t affect Django currently, since we only put this URL into the `Location` response header and browsers seem to ignore JavaScript there. Browsers we tested also treat URLs prefixed with control characters such as `%08//example.com` as relative paths so redirection to an unsafe target isn’t a problem either. However, if a developer relies on `is_safe_url()` to provide safe redirect targets and puts such a URL into a link, they could suffer from an XSS attack as some browsers such as Google Chrome ignore control characters at the start of a URL in an anchor `href`. [**Back to Top](#top) ## Additional Information ### Support Django! * [Nadia Eghbal donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.4.20 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.11.17/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.11.17/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.11.17/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.11.17/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.11.17/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.11.17/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.11.17/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.11.17/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.11.17/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.11.17/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.11.17/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.11.17/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.11.17/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.11.17/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.11.17/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.11.17/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.11.17/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.11.17/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.11.17/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.11.17/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.11.17/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.11.17/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.11.17/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.11.17/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.11.17/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.11.17/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.11.17/) - [**](#top) # Django 1.11.17 release notes[¶](#django-1-11-17-release-notes "Link to this heading") *December 3, 2018* Django 1.11.17 fixes several bugs in 1.11.16 and adds compatibility with Python 3.7. ## Bugfixes[¶](#bugfixes "Link to this heading") * Prevented repetitive calls to `geos_version_tuple()` in the `WKBWriter` class in an attempt to fix a random crash involving `LooseVersion` since Django 1.11.14 ([#29959](https://code.djangoproject.com/ticket/29959)). [**Back to Top](#top) ## Additional Information ### Support Django! * [NoranSoft donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.11.17 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/4.1.5/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/4.1.5/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/4.1.5/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/4.1.5/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/4.1.5/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/4.1.5/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/4.1.5/) - [it](https://docs.djangoproject.com/it/6.1/releases/4.1.5/) - [id](https://docs.djangoproject.com/id/6.1/releases/4.1.5/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/4.1.5/) - [es](https://docs.djangoproject.com/es/6.1/releases/4.1.5/) - [el](https://docs.djangoproject.com/el/6.1/releases/4.1.5/) * * [dev](https://docs.djangoproject.com/en/dev/releases/4.1.5/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/4.1.5/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/4.1.5/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/4.1.5/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/4.1.5/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/4.1.5/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/4.1.5/) - [**](#top) # Django 4.1.5 release notes[¶](#django-4-1-5-release-notes "Link to this heading") *January 2, 2023* Django 4.1.5 fixes a bug in 4.1.4. Also, the latest string translations from Transifex are incorporated. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a long standing bug in the `__len` lookup for `ArrayField` that caused a crash of model validation on [`Meta.constraints`](../../ref/models/options/#django.db.models.Options.constraints "django.db.models.Options.constraints") ([#34205](https://code.djangoproject.com/ticket/34205)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Payer Law Group donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 4.1.5 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/intro/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/intro/) - [sv](https://docs.djangoproject.com/sv/6.1/intro/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/intro/) - [pl](https://docs.djangoproject.com/pl/6.1/intro/) - [ko](https://docs.djangoproject.com/ko/6.1/intro/) - [ja](https://docs.djangoproject.com/ja/6.1/intro/) - [it](https://docs.djangoproject.com/it/6.1/intro/) - [id](https://docs.djangoproject.com/id/6.1/intro/) - [fr](https://docs.djangoproject.com/fr/6.1/intro/) - [es](https://docs.djangoproject.com/es/6.1/intro/) - [el](https://docs.djangoproject.com/el/6.1/intro/) * * [dev](https://docs.djangoproject.com/en/dev/intro/) * [6.0](https://docs.djangoproject.com/en/6.0/intro/) * [5.2](https://docs.djangoproject.com/en/5.2/intro/) * [5.1](https://docs.djangoproject.com/en/5.1/intro/) * [5.0](https://docs.djangoproject.com/en/5.0/intro/) * [4.2](https://docs.djangoproject.com/en/4.2/intro/) * [4.1](https://docs.djangoproject.com/en/4.1/intro/) * [4.0](https://docs.djangoproject.com/en/4.0/intro/) * [3.2](https://docs.djangoproject.com/en/3.2/intro/) * [3.1](https://docs.djangoproject.com/en/3.1/intro/) * [3.0](https://docs.djangoproject.com/en/3.0/intro/) * [2.2](https://docs.djangoproject.com/en/2.2/intro/) * [2.1](https://docs.djangoproject.com/en/2.1/intro/) * [2.0](https://docs.djangoproject.com/en/2.0/intro/) * [1.11](https://docs.djangoproject.com/en/1.11/intro/) * [1.10](https://docs.djangoproject.com/en/1.10/intro/) * [1.9](https://docs.djangoproject.com/en/1.9/intro/) * [1.8](https://docs.djangoproject.com/en/1.8/intro/) - [**](#top) # Getting started[¶](#getting-started "Link to this heading") New to Django? Or to web development in general? Well, you came to the right place: read this material to quickly get up and running. * [Django at a glance](overview/) * [Quick install guide](install/) * [Writing your first Django app, part 1](tutorial01/) * [Writing your first Django app, part 2](tutorial02/) * [Writing your first Django app, part 3](tutorial03/) * [Writing your first Django app, part 4](tutorial04/) * [Writing your first Django app, part 5](tutorial05/) * [Writing your first Django app, part 6](tutorial06/) * [Writing your first Django app, part 7](tutorial07/) * [Writing your first Django app, part 8](tutorial08/) * [Advanced tutorial: How to write reusable apps](reusable-apps/) * [What to read next](whatsnext/) * [Writing your first contribution for Django](contributing/) See also If you’re new to [Python](https://www.python.org/), you might want to start by getting an idea of what the language is like. Django is 100% Python, so if you’ve got minimal comfort with Python you’ll probably get a lot more out of Django. If you’re new to programming entirely, you might want to start with this [list of Python resources for non-programmers](https://wiki.python.org/moin/BeginnersGuide/NonProgrammers) If you already know a few other languages and want to get up to speed with Python quickly, we recommend referring to the official [Python documentation](https://docs.python.org/3/), which provides comprehensive and authoritative information about the language, as well as links to other resources such as a list of [books about Python](https://wiki.python.org/moin/PythonBooks). [**Back to Top](#top) ## Additional Information ### Support Django! * [Jim Munro donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Getting started](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.9.8/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.9.8/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.9.8/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.9.8/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.9.8/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.9.8/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.9.8/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.9.8/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.9.8/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.9.8/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.9.8/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.9.8/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.9.8/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.9.8/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.9.8/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.9.8/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.9.8/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.9.8/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.9.8/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.9.8/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.9.8/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.9.8/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.9.8/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.9.8/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.9.8/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.9.8/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.9.8/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.9.8/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.9.8/) - [**](#top) # Django 1.9.8 release notes[¶](#django-1-9-8-release-notes "Link to this heading") *July 18, 2016* Django 1.9.8 fixes a security issue and several bugs in 1.9.7. ## XSS in admin’s add/change related popup[¶](#xss-in-admin-s-add-change-related-popup "Link to this heading") Unsafe usage of JavaScript’s `Element.innerHTML` could result in XSS in the admin’s add/change related popup. `Element.textContent` is now used to prevent execution of the data. The debug view also used `innerHTML`. Although a security issue wasn’t identified there, out of an abundance of caution it’s also updated to use `textContent`. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed missing `varchar/text_pattern_ops` index on `CharField` and `TextField` respectively when using `AddField` on PostgreSQL ([#26889](https://code.djangoproject.com/ticket/26889)). * Fixed `makemessages` crash on Python 2 with non-ASCII file names ([#26897](https://code.djangoproject.com/ticket/26897)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Vincenzo Romeo donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.9.8 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/topics/db/fixtures/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/db/fixtures/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/db/fixtures/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/db/fixtures/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/db/fixtures/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/db/fixtures/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/db/fixtures/) - [it](https://docs.djangoproject.com/it/6.1/topics/db/fixtures/) - [id](https://docs.djangoproject.com/id/6.1/topics/db/fixtures/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/db/fixtures/) - [es](https://docs.djangoproject.com/es/6.1/topics/db/fixtures/) - [el](https://docs.djangoproject.com/el/6.1/topics/db/fixtures/) * * [dev](https://docs.djangoproject.com/en/dev/topics/db/fixtures/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/db/fixtures/) * [5.2](https://docs.djangoproject.com/en/5.2/topics/db/fixtures/) * [5.1](https://docs.djangoproject.com/en/5.1/topics/db/fixtures/) * [5.0](https://docs.djangoproject.com/en/5.0/topics/db/fixtures/) * [4.2](https://docs.djangoproject.com/en/4.2/topics/db/fixtures/) - [**](#top) # Fixtures[¶](#fixtures "Link to this heading") A *fixture* is a collection of files that contain the serialized contents of the database. Each fixture has a unique name, and the files that comprise the fixture can be distributed over multiple directories, in multiple applications. See also * [How to provide initial data for models](../../../howto/initial-data/) ## How to produce a fixture[¶](#how-to-produce-a-fixture "Link to this heading") Fixtures can be generated by [`manage.py dumpdata`](../../../ref/django-admin/#django-admin-dumpdata). It’s also possible to generate custom fixtures by directly using [serialization tools](../../serialization/) or even by handwriting them. ## How to use a fixture[¶](#how-to-use-a-fixture "Link to this heading") Fixtures can be used to pre-populate the database with data for [tests](../../testing/tools/#topics-testing-fixtures): ``` class MyTestCase(TestCase): fixtures = ["fixture-label"] ``` or to provide some [initial data](../../../howto/initial-data/#initial-data-via-fixtures) using the [`loaddata`](../../../ref/django-admin/#django-admin-loaddata) command: ``` django-admin loaddata ``` ## How fixtures are discovered[¶](#how-fixtures-are-discovered "Link to this heading") Django will search in these locations for fixtures: 1. In the `fixtures` directory of every installed application 2. In any directory listed in the [`FIXTURE_DIRS`](../../../ref/settings/#std-setting-FIXTURE_DIRS) setting 3. In the literal path named by the fixture Django will load any and all fixtures it finds in these locations that match the provided fixture names. If the named fixture has a file extension, only fixtures of that type will be loaded. For example: ``` django-admin loaddata mydata.json ``` would only load JSON fixtures called `mydata`. The fixture extension must correspond to the registered name of a [serializer](../../serialization/#serialization-formats) (e.g., `json` or `xml`). If you omit the extensions, Django will search all available fixture types for a matching fixture. For example: ``` django-admin loaddata mydata ``` would look for any fixture of any fixture type called `mydata`. If a fixture directory contained `mydata.json`, that fixture would be loaded as a JSON fixture. The fixtures that are named can include directory components. These directories will be included in the search path. For example: ``` django-admin loaddata foo/bar/mydata.json ``` would search `/fixtures/foo/bar/mydata.json` for each installed application, `/foo/bar/mydata.json` for each directory in [`FIXTURE_DIRS`](../../../ref/settings/#std-setting-FIXTURE_DIRS), and the literal path `foo/bar/mydata.json`. ### Fixtures loading order[¶](#fixtures-loading-order "Link to this heading") Multiple fixtures can be specified in the same invocation. For example: ``` django-admin loaddata mammals birds insects ``` or in a test case class: ``` class AnimalTestCase(TestCase): fixtures = ["mammals", "birds", "insects"] ``` The order in which fixtures are loaded follows the order in which they are listed, whether it’s when using the management command or when listing them in the test case class as shown above. In these examples, all the fixtures named `mammals` from all applications (in the order in which applications are defined in [`INSTALLED_APPS`](../../../ref/settings/#std-setting-INSTALLED_APPS)) will be loaded first. Subsequently, all the `birds` fixtures will be loaded, followed by all the `insects` fixtures. Be aware that if the database backend supports row-level constraints, these constraints will be checked at the end of the transaction. Any relationships across fixtures may result in a load error if the database configuration does not support deferred constraint checking (refer to the [MySQL](https://dev.mysql.com/doc/refman/en/constraint-foreign-key.html) docs for an example). ## How fixtures are saved to the database[¶](#how-fixtures-are-saved-to-the-database "Link to this heading") When fixture files are processed, the data is saved to the database as is. Model defined [`save()`](../../../ref/models/instances/#django.db.models.Model.save "django.db.models.Model.save") methods are not called, and any [`pre_save`](../../../ref/signals/#django.db.models.signals.pre_save "django.db.models.signals.pre_save"), [`post_save`](../../../ref/signals/#django.db.models.signals.post_save "django.db.models.signals.post_save"), or [`m2m_changed`](../../../ref/signals/#django.db.models.signals.m2m_changed "django.db.models.signals.m2m_changed") signals will be called with `raw=True` since the instance only contains attributes that are local to the model. You may, for example, want to disable handlers that access related fields that aren’t present during fixture loading and would otherwise raise an exception: ``` from django.db.models.signals import post_save from .models import MyModel def my_handler(**kwargs): # disable the handler during fixture loading if kwargs["raw"]: return ... post_save.connect(my_handler, sender=MyModel) ``` You could also write a decorator to encapsulate this logic: ``` from functools import wraps def disable_for_loaddata(signal_handler): """ Decorator that turns off signal handlers when loading fixture data. """ @wraps(signal_handler) def wrapper(*args, **kwargs): if kwargs["raw"]: return signal_handler(*args, **kwargs) return wrapper @disable_for_loaddata def my_handler(**kwargs): ... ``` Just be aware that this logic will disable the signals whenever fixtures are deserialized, not just during [`loaddata`](../../../ref/django-admin/#django-admin-loaddata). Changed in Django 6.1: The `raw` argument was added to `m2m_changed` signals. ## Compressed fixtures[¶](#compressed-fixtures "Link to this heading") Fixtures may be compressed in `zip`, `gz`, `bz2`, `lzma`, or `xz` format. For example: ``` django-admin loaddata mydata.json ``` would look for any of `mydata.json`, `mydata.json.zip`, `mydata.json.gz`, `mydata.json.bz2`, `mydata.json.lzma`, or `mydata.json.xz`. The first file contained within a compressed archive is used. Note that if two fixtures with the same name but different fixture type are discovered (for example, if `mydata.json` and `mydata.xml.gz` were found in the same fixture directory), fixture installation will be aborted, and any data installed in the call to [`loaddata`](../../../ref/django-admin/#django-admin-loaddata) will be removed from the database. MySQL with MyISAM and fixtures The MyISAM storage engine of MySQL doesn’t support transactions or constraints, so if you use MyISAM, you won’t get validation of fixture data, or a rollback if multiple transaction files are found. ## Database-specific fixtures[¶](#database-specific-fixtures "Link to this heading") If you’re in a multi-database setup, you might have fixture data that you want to load onto one database, but not onto another. In this situation, you can add a database identifier into the names of your fixtures. For example, if your [`DATABASES`](../../../ref/settings/#std-setting-DATABASES) setting has a `users` database defined, name the fixture `mydata.users.json` or `mydata.users.json.gz` and the fixture will only be loaded when you specify you want to load data into the `users` database. [**Back to Top](#top) ## Additional Information ### Support Django! * [Christian Ullrich donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Fixtures](#) * [How to produce a fixture](#how-to-produce-a-fixture) * [How to use a fixture](#how-to-use-a-fixture) * [How fixtures are discovered](#how-fixtures-are-discovered) * [Fixtures loading order](#fixtures-loading-order) * [How fixtures are saved to the database](#how-fixtures-are-saved-to-the-database) * [Compressed fixtures](#compressed-fixtures) * [Database-specific fixtures](#database-specific-fixtures) ---- url: https://docs.djangoproject.com/en/6.1/releases/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/) - [it](https://docs.djangoproject.com/it/6.1/releases/) - [id](https://docs.djangoproject.com/id/6.1/releases/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/) - [es](https://docs.djangoproject.com/es/6.1/releases/) - [el](https://docs.djangoproject.com/el/6.1/releases/) * * [dev](https://docs.djangoproject.com/en/dev/releases/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/) - [**](#top) # Release notes[¶](#release-notes "Link to this heading") Release notes for the official Django releases. Each release note will tell you what’s new in each version, and will also describe any backwards-incompatible changes made in that version. For those [upgrading to a new version of Django](../howto/upgrade-version/), you will need to check all the backwards-incompatible changes and [deprecated features](../internals/deprecation/) for each ‘final’ release from the one after your current Django version, up to and including the new version. ## Final releases[¶](#final-releases "Link to this heading") Below are release notes through Django 6.1 and its patch releases. Newer versions of the documentation contain the release notes for any later releases. ### 6.1 release[¶](#release "Link to this heading") * [Django 6.1.3 release notes](6.1.3/) * [Django 6.1.2 release notes](6.1.2/) * [Django 6.1.1 release notes](6.1.1/) * [Django 6.1 release notes](6.1/) ### 6.0 release[¶](#id1 "Link to this heading") * [Django 6.0.9 release notes](6.0.9/) * [Django 6.0.8 release notes](6.0.8/) * [Django 6.0.7 release notes](6.0.7/) * [Django 6.0.6 release notes](6.0.6/) * [Django 6.0.5 release notes](6.0.5/) * [Django 6.0.4 release notes](6.0.4/) * [Django 6.0.3 release notes](6.0.3/) * [Django 6.0.2 release notes](6.0.2/) * [Django 6.0.1 release notes](6.0.1/) * [Django 6.0 release notes](6.0/) ### 5.2 release[¶](#id2 "Link to this heading") * [Django 5.2.18 release notes](5.2.18/) * [Django 5.2.17 release notes](5.2.17/) * [Django 5.2.16 release notes](5.2.16/) * [Django 5.2.15 release notes](5.2.15/) * [Django 5.2.14 release notes](5.2.14/) * [Django 5.2.13 release notes](5.2.13/) * [Django 5.2.12 release notes](5.2.12/) * [Django 5.2.11 release notes](5.2.11/) * [Django 5.2.10 release notes](5.2.10/) * [Django 5.2.9 release notes](5.2.9/) * [Django 5.2.8 release notes](5.2.8/) * [Django 5.2.7 release notes](5.2.7/) * [Django 5.2.6 release notes](5.2.6/) * [Django 5.2.5 release notes](5.2.5/) * [Django 5.2.4 release notes](5.2.4/) * [Django 5.2.3 release notes](5.2.3/) * [Django 5.2.2 release notes](5.2.2/) * [Django 5.2.1 release notes](5.2.1/) * [Django 5.2 release notes](5.2/) ### 5.1 release[¶](#id3 "Link to this heading") * [Django 5.1.15 release notes](5.1.15/) * [Django 5.1.14 release notes](5.1.14/) * [Django 5.1.13 release notes](5.1.13/) * [Django 5.1.12 release notes](5.1.12/) * [Django 5.1.11 release notes](5.1.11/) * [Django 5.1.10 release notes](5.1.10/) * [Django 5.1.9 release notes](5.1.9/) * [Django 5.1.8 release notes](5.1.8/) * [Django 5.1.7 release notes](5.1.7/) * [Django 5.1.6 release notes](5.1.6/) * [Django 5.1.5 release notes](5.1.5/) * [Django 5.1.4 release notes](5.1.4/) * [Django 5.1.3 release notes](5.1.3/) * [Django 5.1.2 release notes](5.1.2/) * [Django 5.1.1 release notes](5.1.1/) * [Django 5.1 release notes](5.1/) ### 5.0 release[¶](#id4 "Link to this heading") * [Django 5.0.14 release notes](5.0.14/) * [Django 5.0.13 release notes](5.0.13/) * [Django 5.0.12 release notes](5.0.12/) * [Django 5.0.11 release notes](5.0.11/) * [Django 5.0.10 release notes](5.0.10/) * [Django 5.0.9 release notes](5.0.9/) * [Django 5.0.8 release notes](5.0.8/) * [Django 5.0.7 release notes](5.0.7/) * [Django 5.0.6 release notes](5.0.6/) * [Django 5.0.5 release notes](5.0.5/) * [Django 5.0.4 release notes](5.0.4/) * [Django 5.0.3 release notes](5.0.3/) * [Django 5.0.2 release notes](5.0.2/) * [Django 5.0.1 release notes](5.0.1/) * [Django 5.0 release notes](5.0/) ### 4.2 release[¶](#id5 "Link to this heading") * [Django 4.2.30 release notes](4.2.30/) * [Django 4.2.29 release notes](4.2.29/) * [Django 4.2.28 release notes](4.2.28/) * [Django 4.2.27 release notes](4.2.27/) * [Django 4.2.26 release notes](4.2.26/) * [Django 4.2.25 release notes](4.2.25/) * [Django 4.2.24 release notes](4.2.24/) * [Django 4.2.23 release notes](4.2.23/) * [Django 4.2.22 release notes](4.2.22/) * [Django 4.2.21 release notes](4.2.21/) * [Django 4.2.20 release notes](4.2.20/) * [Django 4.2.19 release notes](4.2.19/) * [Django 4.2.18 release notes](4.2.18/) * [Django 4.2.17 release notes](4.2.17/) * [Django 4.2.16 release notes](4.2.16/) * [Django 4.2.15 release notes](4.2.15/) * [Django 4.2.14 release notes](4.2.14/) * [Django 4.2.13 release notes](4.2.13/) * [Django 4.2.12 release notes](4.2.12/) * [Django 4.2.11 release notes](4.2.11/) * [Django 4.2.10 release notes](4.2.10/) * [Django 4.2.9 release notes](4.2.9/) * [Django 4.2.8 release notes](4.2.8/) * [Django 4.2.7 release notes](4.2.7/) * [Django 4.2.6 release notes](4.2.6/) * [Django 4.2.5 release notes](4.2.5/) * [Django 4.2.4 release notes](4.2.4/) * [Django 4.2.3 release notes](4.2.3/) * [Django 4.2.2 release notes](4.2.2/) * [Django 4.2.1 release notes](4.2.1/) * [Django 4.2 release notes](4.2/) ### 4.1 release[¶](#id6 "Link to this heading") * [Django 4.1.13 release notes](4.1.13/) * [Django 4.1.12 release notes](4.1.12/) * [Django 4.1.11 release notes](4.1.11/) * [Django 4.1.10 release notes](4.1.10/) * [Django 4.1.9 release notes](4.1.9/) * [Django 4.1.8 release notes](4.1.8/) * [Django 4.1.7 release notes](4.1.7/) * [Django 4.1.6 release notes](4.1.6/) * [Django 4.1.5 release notes](4.1.5/) * [Django 4.1.4 release notes](4.1.4/) * [Django 4.1.3 release notes](4.1.3/) * [Django 4.1.2 release notes](4.1.2/) * [Django 4.1.1 release notes](4.1.1/) * [Django 4.1 release notes](4.1/) ### 4.0 release[¶](#id7 "Link to this heading") * [Django 4.0.10 release notes](4.0.10/) * [Django 4.0.9 release notes](4.0.9/) * [Django 4.0.8 release notes](4.0.8/) * [Django 4.0.7 release notes](4.0.7/) * [Django 4.0.6 release notes](4.0.6/) * [Django 4.0.5 release notes](4.0.5/) * [Django 4.0.4 release notes](4.0.4/) * [Django 4.0.3 release notes](4.0.3/) * [Django 4.0.2 release notes](4.0.2/) * [Django 4.0.1 release notes](4.0.1/) * [Django 4.0 release notes](4.0/) ### 3.2 release[¶](#id8 "Link to this heading") * [Django 3.2.25 release notes](3.2.25/) * [Django 3.2.24 release notes](3.2.24/) * [Django 3.2.23 release notes](3.2.23/) * [Django 3.2.22 release notes](3.2.22/) * [Django 3.2.21 release notes](3.2.21/) * [Django 3.2.20 release notes](3.2.20/) * [Django 3.2.19 release notes](3.2.19/) * [Django 3.2.18 release notes](3.2.18/) * [Django 3.2.17 release notes](3.2.17/) * [Django 3.2.16 release notes](3.2.16/) * [Django 3.2.15 release notes](3.2.15/) * [Django 3.2.14 release notes](3.2.14/) * [Django 3.2.13 release notes](3.2.13/) * [Django 3.2.12 release notes](3.2.12/) * [Django 3.2.11 release notes](3.2.11/) * [Django 3.2.10 release notes](3.2.10/) * [Django 3.2.9 release notes](3.2.9/) * [Django 3.2.8 release notes](3.2.8/) * [Django 3.2.7 release notes](3.2.7/) * [Django 3.2.6 release notes](3.2.6/) * [Django 3.2.5 release notes](3.2.5/) * [Django 3.2.4 release notes](3.2.4/) * [Django 3.2.3 release notes](3.2.3/) * [Django 3.2.2 release notes](3.2.2/) * [Django 3.2.1 release notes](3.2.1/) * [Django 3.2 release notes](3.2/) ### 3.1 release[¶](#id9 "Link to this heading") * [Django 3.1.14 release notes](3.1.14/) * [Django 3.1.13 release notes](3.1.13/) * [Django 3.1.12 release notes](3.1.12/) * [Django 3.1.11 release notes](3.1.11/) * [Django 3.1.10 release notes](3.1.10/) * [Django 3.1.9 release notes](3.1.9/) * [Django 3.1.8 release notes](3.1.8/) * [Django 3.1.7 release notes](3.1.7/) * [Django 3.1.6 release notes](3.1.6/) * [Django 3.1.5 release notes](3.1.5/) * [Django 3.1.4 release notes](3.1.4/) * [Django 3.1.3 release notes](3.1.3/) * [Django 3.1.2 release notes](3.1.2/) * [Django 3.1.1 release notes](3.1.1/) * [Django 3.1 release notes](3.1/) ### 3.0 release[¶](#id10 "Link to this heading") * [Django 3.0.14 release notes](3.0.14/) * [Django 3.0.13 release notes](3.0.13/) * [Django 3.0.12 release notes](3.0.12/) * [Django 3.0.11 release notes](3.0.11/) * [Django 3.0.10 release notes](3.0.10/) * [Django 3.0.9 release notes](3.0.9/) * [Django 3.0.8 release notes](3.0.8/) * [Django 3.0.7 release notes](3.0.7/) * [Django 3.0.6 release notes](3.0.6/) * [Django 3.0.5 release notes](3.0.5/) * [Django 3.0.4 release notes](3.0.4/) * [Django 3.0.3 release notes](3.0.3/) * [Django 3.0.2 release notes](3.0.2/) * [Django 3.0.1 release notes](3.0.1/) * [Django 3.0 release notes](3.0/) ### 2.2 release[¶](#id11 "Link to this heading") * [Django 2.2.28 release notes](2.2.28/) * [Django 2.2.27 release notes](2.2.27/) * [Django 2.2.26 release notes](2.2.26/) * [Django 2.2.25 release notes](2.2.25/) * [Django 2.2.24 release notes](2.2.24/) * [Django 2.2.23 release notes](2.2.23/) * [Django 2.2.22 release notes](2.2.22/) * [Django 2.2.21 release notes](2.2.21/) * [Django 2.2.20 release notes](2.2.20/) * [Django 2.2.19 release notes](2.2.19/) * [Django 2.2.18 release notes](2.2.18/) * [Django 2.2.17 release notes](2.2.17/) * [Django 2.2.16 release notes](2.2.16/) * [Django 2.2.15 release notes](2.2.15/) * [Django 2.2.14 release notes](2.2.14/) * [Django 2.2.13 release notes](2.2.13/) * [Django 2.2.12 release notes](2.2.12/) * [Django 2.2.11 release notes](2.2.11/) * [Django 2.2.10 release notes](2.2.10/) * [Django 2.2.9 release notes](2.2.9/) * [Django 2.2.8 release notes](2.2.8/) * [Django 2.2.7 release notes](2.2.7/) * [Django 2.2.6 release notes](2.2.6/) * [Django 2.2.5 release notes](2.2.5/) * [Django 2.2.4 release notes](2.2.4/) * [Django 2.2.3 release notes](2.2.3/) * [Django 2.2.2 release notes](2.2.2/) * [Django 2.2.1 release notes](2.2.1/) * [Django 2.2 release notes](2.2/) ### 2.1 release[¶](#id12 "Link to this heading") * [Django 2.1.15 release notes](2.1.15/) * [Django 2.1.14 release notes](2.1.14/) * [Django 2.1.13 release notes](2.1.13/) * [Django 2.1.12 release notes](2.1.12/) * [Django 2.1.11 release notes](2.1.11/) * [Django 2.1.10 release notes](2.1.10/) * [Django 2.1.9 release notes](2.1.9/) * [Django 2.1.8 release notes](2.1.8/) * [Django 2.1.7 release notes](2.1.7/) * [Django 2.1.6 release notes](2.1.6/) * [Django 2.1.5 release notes](2.1.5/) * [Django 2.1.4 release notes](2.1.4/) * [Django 2.1.3 release notes](2.1.3/) * [Django 2.1.2 release notes](2.1.2/) * [Django 2.1.1 release notes](2.1.1/) * [Django 2.1 release notes](2.1/) ### 2.0 release[¶](#id13 "Link to this heading") * [Django 2.0.13 release notes](2.0.13/) * [Django 2.0.12 release notes](2.0.12/) * [Django 2.0.11 release notes](2.0.11/) * [Django 2.0.10 release notes](2.0.10/) * [Django 2.0.9 release notes](2.0.9/) * [Django 2.0.8 release notes](2.0.8/) * [Django 2.0.7 release notes](2.0.7/) * [Django 2.0.6 release notes](2.0.6/) * [Django 2.0.5 release notes](2.0.5/) * [Django 2.0.4 release notes](2.0.4/) * [Django 2.0.3 release notes](2.0.3/) * [Django 2.0.2 release notes](2.0.2/) * [Django 2.0.1 release notes](2.0.1/) * [Django 2.0 release notes](2.0/) ### 1.11 release[¶](#id14 "Link to this heading") * [Django 1.11.29 release notes](1.11.29/) * [Django 1.11.28 release notes](1.11.28/) * [Django 1.11.27 release notes](1.11.27/) * [Django 1.11.26 release notes](1.11.26/) * [Django 1.11.25 release notes](1.11.25/) * [Django 1.11.24 release notes](1.11.24/) * [Django 1.11.23 release notes](1.11.23/) * [Django 1.11.22 release notes](1.11.22/) * [Django 1.11.21 release notes](1.11.21/) * [Django 1.11.20 release notes](1.11.20/) * [Django 1.11.19 release notes](1.11.19/) * [Django 1.11.18 release notes](1.11.18/) * [Django 1.11.17 release notes](1.11.17/) * [Django 1.11.16 release notes](1.11.16/) * [Django 1.11.15 release notes](1.11.15/) * [Django 1.11.14 release notes](1.11.14/) * [Django 1.11.13 release notes](1.11.13/) * [Django 1.11.12 release notes](1.11.12/) * [Django 1.11.11 release notes](1.11.11/) * [Django 1.11.10 release notes](1.11.10/) * [Django 1.11.9 release notes](1.11.9/) * [Django 1.11.8 release notes](1.11.8/) * [Django 1.11.7 release notes](1.11.7/) * [Django 1.11.6 release notes](1.11.6/) * [Django 1.11.5 release notes](1.11.5/) * [Django 1.11.4 release notes](1.11.4/) * [Django 1.11.3 release notes](1.11.3/) * [Django 1.11.2 release notes](1.11.2/) * [Django 1.11.1 release notes](1.11.1/) * [Django 1.11 release notes](1.11/) ### 1.10 release[¶](#id15 "Link to this heading") * [Django 1.10.8 release notes](1.10.8/) * [Django 1.10.7 release notes](1.10.7/) * [Django 1.10.6 release notes](1.10.6/) * [Django 1.10.5 release notes](1.10.5/) * [Django 1.10.4 release notes](1.10.4/) * [Django 1.10.3 release notes](1.10.3/) * [Django 1.10.2 release notes](1.10.2/) * [Django 1.10.1 release notes](1.10.1/) * [Django 1.10 release notes](1.10/) ### 1.9 release[¶](#id16 "Link to this heading") * [Django 1.9.13 release notes](1.9.13/) * [Django 1.9.12 release notes](1.9.12/) * [Django 1.9.11 release notes](1.9.11/) * [Django 1.9.10 release notes](1.9.10/) * [Django 1.9.9 release notes](1.9.9/) * [Django 1.9.8 release notes](1.9.8/) * [Django 1.9.7 release notes](1.9.7/) * [Django 1.9.6 release notes](1.9.6/) * [Django 1.9.5 release notes](1.9.5/) * [Django 1.9.4 release notes](1.9.4/) * [Django 1.9.3 release notes](1.9.3/) * [Django 1.9.2 release notes](1.9.2/) * [Django 1.9.1 release notes](1.9.1/) * [Django 1.9 release notes](1.9/) ### 1.8 release[¶](#id17 "Link to this heading") * [Django 1.8.19 release notes](1.8.19/) * [Django 1.8.18 release notes](1.8.18/) * [Django 1.8.17 release notes](1.8.17/) * [Django 1.8.16 release notes](1.8.16/) * [Django 1.8.15 release notes](1.8.15/) * [Django 1.8.14 release notes](1.8.14/) * [Django 1.8.13 release notes](1.8.13/) * [Django 1.8.12 release notes](1.8.12/) * [Django 1.8.11 release notes](1.8.11/) * [Django 1.8.10 release notes](1.8.10/) * [Django 1.8.9 release notes](1.8.9/) * [Django 1.8.8 release notes](1.8.8/) * [Django 1.8.7 release notes](1.8.7/) * [Django 1.8.6 release notes](1.8.6/) * [Django 1.8.5 release notes](1.8.5/) * [Django 1.8.4 release notes](1.8.4/) * [Django 1.8.3 release notes](1.8.3/) * [Django 1.8.2 release notes](1.8.2/) * [Django 1.8.1 release notes](1.8.1/) * [Django 1.8 release notes](1.8/) ### 1.7 release[¶](#id18 "Link to this heading") * [Django 1.7.11 release notes](1.7.11/) * [Django 1.7.10 release notes](1.7.10/) * [Django 1.7.9 release notes](1.7.9/) * [Django 1.7.8 release notes](1.7.8/) * [Django 1.7.7 release notes](1.7.7/) * [Django 1.7.6 release notes](1.7.6/) * [Django 1.7.5 release notes](1.7.5/) * [Django 1.7.4 release notes](1.7.4/) * [Django 1.7.3 release notes](1.7.3/) * [Django 1.7.2 release notes](1.7.2/) * [Django 1.7.1 release notes](1.7.1/) * [Django 1.7 release notes](1.7/) ### 1.6 release[¶](#id19 "Link to this heading") * [Django 1.6.11 release notes](1.6.11/) * [Django 1.6.10 release notes](1.6.10/) * [Django 1.6.9 release notes](1.6.9/) * [Django 1.6.8 release notes](1.6.8/) * [Django 1.6.7 release notes](1.6.7/) * [Django 1.6.6 release notes](1.6.6/) * [Django 1.6.5 release notes](1.6.5/) * [Django 1.6.4 release notes](1.6.4/) * [Django 1.6.3 release notes](1.6.3/) * [Django 1.6.2 release notes](1.6.2/) * [Django 1.6.1 release notes](1.6.1/) * [Django 1.6 release notes](1.6/) ### 1.5 release[¶](#id20 "Link to this heading") * [Django 1.5.12 release notes](1.5.12/) * [Django 1.5.11 release notes](1.5.11/) * [Django 1.5.10 release notes](1.5.10/) * [Django 1.5.9 release notes](1.5.9/) * [Django 1.5.8 release notes](1.5.8/) * [Django 1.5.7 release notes](1.5.7/) * [Django 1.5.6 release notes](1.5.6/) * [Django 1.5.5 release notes](1.5.5/) * [Django 1.5.4 release notes](1.5.4/) * [Django 1.5.3 release notes](1.5.3/) * [Django 1.5.2 release notes](1.5.2/) * [Django 1.5.1 release notes](1.5.1/) * [Django 1.5 release notes](1.5/) ### 1.4 release[¶](#id21 "Link to this heading") * [Django 1.4.22 release notes](1.4.22/) * [Django 1.4.21 release notes](1.4.21/) * [Django 1.4.20 release notes](1.4.20/) * [Django 1.4.19 release notes](1.4.19/) * [Django 1.4.18 release notes](1.4.18/) * [Django 1.4.17 release notes](1.4.17/) * [Django 1.4.16 release notes](1.4.16/) * [Django 1.4.15 release notes](1.4.15/) * [Django 1.4.14 release notes](1.4.14/) * [Django 1.4.13 release notes](1.4.13/) * [Django 1.4.12 release notes](1.4.12/) * [Django 1.4.11 release notes](1.4.11/) * [Django 1.4.10 release notes](1.4.10/) * [Django 1.4.9 release notes](1.4.9/) * [Django 1.4.8 release notes](1.4.8/) * [Django 1.4.7 release notes](1.4.7/) * [Django 1.4.6 release notes](1.4.6/) * [Django 1.4.5 release notes](1.4.5/) * [Django 1.4.4 release notes](1.4.4/) * [Django 1.4.3 release notes](1.4.3/) * [Django 1.4.2 release notes](1.4.2/) * [Django 1.4.1 release notes](1.4.1/) * [Django 1.4 release notes](1.4/) ### 1.3 release[¶](#id22 "Link to this heading") * [Django 1.3.7 release notes](1.3.7/) * [Django 1.3.6 release notes](1.3.6/) * [Django 1.3.5 release notes](1.3.5/) * [Django 1.3.4 release notes](1.3.4/) * [Django 1.3.3 release notes](1.3.3/) * [Django 1.3.2 release notes](1.3.2/) * [Django 1.3.1 release notes](1.3.1/) * [Django 1.3 release notes](1.3/) ### 1.2 release[¶](#id23 "Link to this heading") * [Django 1.2.7 release notes](1.2.7/) * [Django 1.2.6 release notes](1.2.6/) * [Django 1.2.5 release notes](1.2.5/) * [Django 1.2.4 release notes](1.2.4/) * [Django 1.2.3 release notes](1.2.3/) * [Django 1.2.2 release notes](1.2.2/) * [Django 1.2.1 release notes](1.2.1/) * [Django 1.2 release notes](1.2/) ### 1.1 release[¶](#id24 "Link to this heading") * [Django 1.1.4 release notes](1.1.4/) * [Django 1.1.3 release notes](1.1.3/) * [Django 1.1.2 release notes](1.1.2/) * [Django 1.1 release notes](1.1/) ### 1.0 release[¶](#id25 "Link to this heading") * [Django 1.0.2 release notes](1.0.2/) * [Django 1.0.1 release notes](1.0.1/) * [Django 1.0 release notes](1.0/) ### Pre-1.0 releases[¶](#pre-1-0-releases "Link to this heading") * [Django version 0.96 release notes](0.96/) * [Django version 0.95 release notes](0.95/) ## Security releases[¶](#security-releases "Link to this heading") Whenever a security issue is disclosed via [Django’s security policies](../internals/security/), appropriate release notes are now added to all affected release series. Additionally, [an archive of disclosed security issues](security/) is maintained. [**Back to Top](#top) ## Additional Information ### Support Django! * [Tyrel Souza donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Release notes](#) * [Final releases](#final-releases) * [6.1 release](#release) * [6.0 release](#id1) * [5.2 release](#id2) * [5.1 release](#id3) * [5.0 release](#id4) * [4.2 release](#id5) * [4.1 release](#id6) * [4.0 release](#id7) * [3.2 release](#id8) * [3.1 release](#id9) * [3.0 release](#id10) * [2.2 release](#id11) * [2.1 release](#id12) * [2.0 release](#id13) * [1.11 release](#id14) * [1.10 release](#id15) * [1.9 release](#id16) * [1.8 release](#id17) * [1.7 release](#id18) * [1.6 release](#id19) * [1.5 release](#id20) * [1.4 release](#id21) * [1.3 release](#id22) * [1.2 release](#id23) * [1.1 release](#id24) * [1.0 release](#id25) * [Pre-1.0 releases](#pre-1-0-releases) * [Security releases](#security-releases) ---- url: https://docs.djangoproject.com/en/6.1/howto/mailers-migration/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/howto/mailers-migration/) - [sv](https://docs.djangoproject.com/sv/6.1/howto/mailers-migration/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/howto/mailers-migration/) - [pl](https://docs.djangoproject.com/pl/6.1/howto/mailers-migration/) - [ko](https://docs.djangoproject.com/ko/6.1/howto/mailers-migration/) - [ja](https://docs.djangoproject.com/ja/6.1/howto/mailers-migration/) - [it](https://docs.djangoproject.com/it/6.1/howto/mailers-migration/) - [id](https://docs.djangoproject.com/id/6.1/howto/mailers-migration/) - [fr](https://docs.djangoproject.com/fr/6.1/howto/mailers-migration/) - [es](https://docs.djangoproject.com/es/6.1/howto/mailers-migration/) - [el](https://docs.djangoproject.com/el/6.1/howto/mailers-migration/) * * [dev](https://docs.djangoproject.com/en/dev/howto/mailers-migration/) - [**](#top) # Migrating email to mailers[¶](#migrating-email-to-mailers "Link to this heading") Django 6.1 introduced the [`MAILERS`](../../ref/settings/#std-setting-MAILERS) setting, replacing [`EMAIL_BACKEND`](../../ref/settings/#std-setting-EMAIL_BACKEND) and several other `EMAIL_*` settings. It also introduced [`mail.mailers`](../../topics/email/#django.core.mail.mailers "django.core.mail.mailers") for obtaining configured email backend instances, replacing [`mail.get_connection()`](../../topics/email/#django.core.mail.get_connection "django.core.mail.get_connection"). A new `using` argument replaces the earlier `connection` in Django functions that send email. This guide provides details on migrating existing projects to the new mailers functionality. All Django projects that send email should: * If using any third-party packages that send email, [verify their compatibility](#migrating-to-mailers-third-party) with [`MAILERS`](../../ref/settings/#std-setting-MAILERS) before making other changes. * [Update email-related settings](#migrating-to-mailers-settings). * Run with deprecation warnings enabled (see [Resolving deprecation warnings](../upgrade-version/#resolving-deprecation-warnings)) to identify other code needing updates. Note Running tests may not identify all relevant deprecations. Test suites often use a non-functional email backend (such as the memory backend that Django [substitutes during tests](../../topics/testing/tools/#topics-testing-email)), so can miss deprecation warnings that are only issued from the production email configuration. Consider running with deprecation warnings enabled in production to catch those deprecations. Or carefully review your code (including third-party packages) for use of any deprecated email features. Other updates are needed only for projects or reusable Django libraries that use these specific features: * [Replacing get\_connection() and connection arguments](#migrating-to-mailers-get-connection) * [Replacing fail\_silently](#migrating-to-mailers-fail-silently) * [Migrating custom email backends](#migrating-to-mailers-email-backends) * [Replacing auth\_user and auth\_password](#migrating-to-mailers-auth) * [Updating AdminEmailHandler email\_backend](#migrating-to-mailers-adminemailhandler) * [Ignoring transient failures in error reporting](#migrating-to-mailers-error-reporting) Deprecated since version 6.1: The following settings and functions will be removed in Django 2028: * [`EMAIL_BACKEND`](../../ref/settings/#std-setting-EMAIL_BACKEND), [`EMAIL_FILE_PATH`](../../ref/settings/#std-setting-EMAIL_FILE_PATH), [`EMAIL_HOST`](../../ref/settings/#std-setting-EMAIL_HOST), [`EMAIL_HOST_PASSWORD`](../../ref/settings/#std-setting-EMAIL_HOST_PASSWORD), [`EMAIL_HOST_USER`](../../ref/settings/#std-setting-EMAIL_HOST_USER), [`EMAIL_PORT`](../../ref/settings/#std-setting-EMAIL_PORT), [`EMAIL_SSL_CERTFILE`](../../ref/settings/#std-setting-EMAIL_SSL_CERTFILE), [`EMAIL_SSL_KEYFILE`](../../ref/settings/#std-setting-EMAIL_SSL_KEYFILE), [`EMAIL_TIMEOUT`](../../ref/settings/#std-setting-EMAIL_TIMEOUT), [`EMAIL_USE_SSL`](../../ref/settings/#std-setting-EMAIL_USE_SSL), [`EMAIL_USE_TLS`](../../ref/settings/#std-setting-EMAIL_USE_TLS) * [`mail.get_connection()`](../../topics/email/#django.core.mail.get_connection "django.core.mail.get_connection") and the `connection` arguments to mail functions * The `fail_silently` argument to [`send_mail()`](../../topics/email/#django.core.mail.send_mail "django.core.mail.send_mail"), [`send_mass_mail()`](../../topics/email/#django.core.mail.send_mass_mail "django.core.mail.send_mass_mail"), [`mail_admins()`](../../topics/email/#django.core.mail.mail_admins "django.core.mail.mail_admins"), [`mail_managers()`](../../topics/email/#django.core.mail.mail_managers "django.core.mail.mail_managers"), and [`EmailMessage.send()`](../../topics/email/#django.core.mail.EmailMessage.send "django.core.mail.EmailMessage.send") * The `auth_user` and `auth_password` arguments to [`send_mail()`](../../topics/email/#django.core.mail.send_mail "django.core.mail.send_mail") and [`send_mass_mail()`](../../topics/email/#django.core.mail.send_mass_mail "django.core.mail.send_mass_mail") * The `email_backend` argument to [`AdminEmailHandler`](../../ref/logging/#django.utils.log.AdminEmailHandler "django.utils.log.AdminEmailHandler") ## Migrating settings[¶](#migrating-settings "Link to this heading") Often, the only change needed to migrate to mailers is updating email-related settings. In your project’s settings, define a [`MAILERS`](../../ref/settings/#std-setting-MAILERS) dict with a `"default"` entry matching the earlier `EMAIL_*` settings: ``` MAILERS = { "default": { "BACKEND": ..., # value of EMAIL_BACKEND setting "OPTIONS": { # values from other deprecated EMAIL_* settings ..., }, }, } ``` For example, to update these settings: ``` EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend" EMAIL_HOST = "mail.example.net" EMAIL_USE_TLS = True EMAIL_PORT = 587 EMAIL_HOST_USER = "user@example.net" EMAIL_HOST_PASSWORD = "password" ``` use: ``` MAILERS = { "default": { "BACKEND": "django.core.mail.backends.smtp.EmailBackend", "OPTIONS": { "host": "mail.example.net", "use_tls": True, # port is not needed: it defaults to 587 with use_tls True. "username": "user@example.net", "password": "password", }, }, } ``` The complete list of deprecated `EMAIL_*` settings and where they should be moved in a [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration is: * [`EMAIL_BACKEND`](../../ref/settings/#std-setting-EMAIL_BACKEND) becomes `"BACKEND"`. If your settings didn’t define `EMAIL_BACKEND`, the default value was `"django.core.mail.backends.smtp.EmailBackend"` (which is also the default if a [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration doesn’t specify the `"BACKEND"`). * [`EMAIL_FILE_PATH`](../../ref/settings/#std-setting-EMAIL_FILE_PATH) becomes `"file_path"` in `"OPTIONS"` (with `"BACKEND"` set to `"django.core.mail.backends.filebased.EmailBackend"`). * [`EMAIL_HOST`](../../ref/settings/#std-setting-EMAIL_HOST) becomes `"host"` in `"OPTIONS"`. A `"host"` is required for the SMTP email backend. If your settings didn’t define `EMAIL_HOST`, set `"host"` to `"localhost"` (the default value for the deprecated setting). * [`EMAIL_HOST_PASSWORD`](../../ref/settings/#std-setting-EMAIL_HOST_PASSWORD) becomes `"password"` in `"OPTIONS"`. * [`EMAIL_HOST_USER`](../../ref/settings/#std-setting-EMAIL_HOST_USER) becomes `"username"` in `"OPTIONS"`. (Note `"username"` doesn’t quite follow the naming pattern for the other deprecated settings.) * [`EMAIL_PORT`](../../ref/settings/#std-setting-EMAIL_PORT) becomes `"port"` in `"OPTIONS"`. It can be omitted if the connection uses the default port for its security (465 for SSL, 587 for TLS, or 25 for an unsecured SMTP connection). * [`EMAIL_SSL_CERTFILE`](../../ref/settings/#std-setting-EMAIL_SSL_CERTFILE) becomes `"ssl_certfile"` in `"OPTIONS"`. * [`EMAIL_SSL_KEYFILE`](../../ref/settings/#std-setting-EMAIL_SSL_KEYFILE) becomes `"ssl_keyfile"` in `"OPTIONS"`. * [`EMAIL_TIMEOUT`](../../ref/settings/#std-setting-EMAIL_TIMEOUT) becomes `"timeout"` in `"OPTIONS"`. * [`EMAIL_USE_SSL`](../../ref/settings/#std-setting-EMAIL_USE_SSL) becomes `"use_ssl"` in `"OPTIONS"`. * [`EMAIL_USE_TLS`](../../ref/settings/#std-setting-EMAIL_USE_TLS) becomes `"use_tls"` in `"OPTIONS"`. For third-party or custom email backends, the available `"OPTIONS"` depend on the backend. Refer to the third-party documentation, or for custom backends see [Migrating custom email backends](#migrating-to-mailers-email-backends) below. The [Configuring email](../../topics/email/#topic-email-configuration) topic has more information on the `MAILERS` setting and additional configuration examples. ## Reusable library readiness[¶](#reusable-library-readiness "Link to this heading") In most cases, third-party packages that send email through Django will continue working with projects whose settings have been upgraded to use [`MAILERS`](../../ref/settings/#std-setting-MAILERS). (If they use any deprecated mail features, those will of course cause deprecation warnings.) There are two deprecated features that are *not* supported when [`MAILERS`](../../ref/settings/#std-setting-MAILERS) is defined in a project’s settings: * Trying to access any of the deprecated `EMAIL_*` settings on `django.conf.settings` (e.g., checking `settings.EMAIL_BACKEND` or using `settings.EMAIL_HOST_USER`). * Calling [`mail.get_connection("path.to.EmailBackend")`](../../topics/email/#django.core.mail.get_connection "django.core.mail.get_connection") with a specific backend path. (Other arguments to `get_connection()` are still supported, and will simply issue deprecation warnings when [`MAILERS`](../../ref/settings/#std-setting-MAILERS) is defined.) If a third-party package does either of those, projects that use it will not be able to change to the [`MAILERS`](../../ref/settings/#std-setting-MAILERS) setting until the package has been updated. ### Solving “not available when MAILERS is defined” errors[¶](#solving-not-available-when-mailers-is-defined-errors "Link to this heading") If either of these errors are raised within a third-party package, that indicates it is not compatible with the [`MAILERS`](../../ref/settings/#std-setting-MAILERS) setting: * `AttributeError: "The name setting is not available when MAILERS is defined"` where *name* is [`EMAIL_BACKEND`](../../ref/settings/#std-setting-EMAIL_BACKEND), [`EMAIL_HOST`](../../ref/settings/#std-setting-EMAIL_HOST), or one of the other deprecated settings. * `RuntimeError: get_connection(backend, ...) is not supported with MAILERS.` If you see these errors, check if a newer version of that dependency is available. If not (and if there are no alternatives to that package), you will need to remove [`MAILERS`](../../ref/settings/#std-setting-MAILERS) from your settings and replace it with the equivalent [deprecated email settings](#deprecated-email-settings) until the package has been updated. If those errors are coming from your own code, see the other sections in this migration guide for recommended updates. ## Replacing `get_connection()` and `connection` arguments[¶](#replacing-get-connection-and-connection-arguments "Link to this heading") The replacements for the deprecated [`mail.get_connection()`](../../topics/email/#django.core.mail.get_connection "django.core.mail.get_connection") function and `connection` arguments to other mail functions depend on how and why the connections are being created: * `get_connection()` called with no arguments Replace with [`mailers.default`](../../topics/email/#django.core.mail.mailers.default "django.core.mail.mailers.default"). For example, update this code: ``` connection = mail.get_connection() connection.send_messages([email1, email2]) ``` To: ``` connection = mail.mailers.default connection.send_messages([email1, email2]) ``` Note that `mailers.default` *is* the default for Django’s mail-sending functions. Code like this: ``` mail.send_mail(..., connection=mail.get_connection()) ``` can be updated to: ``` mail.send_mail(...) # No connection arg needed. ``` * `get_connection(fail_silently=True)` See [Replacing fail\_silently](#migrating-to-mailers-fail-silently). * `get_connection(...)` called with any other arguments Define a custom [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration with the desired backend and options. Then refer to it in the `using` argument when sending mail, or obtain an email backend instance from [`mail.mailers`](../../topics/email/#django.core.mail.mailers "django.core.mail.mailers") with the configuration name. For example, to upgrade this code: ``` connection = mail.get_connection( "path.to.custom.EmailBackend", option1=True, option2="value" ) mail.send_mail(..., connection=connection) connection.send_messages([email1, email2]) ``` Define a custom [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration in your settings: ``` MAILERS = { "default": {...}, "custom": { "BACKEND": "path.to.custom.EmailBackend", "OPTIONS": { "option1": True, "option2": "value", }, }, } ``` And then use it like this: ``` mail.send_mail(..., using="custom") mail.mailers["custom"].send_messages([email1, email2]) ``` ## Replacing `fail_silently`[¶](#replacing-fail-silently "Link to this heading") The deprecated `fail_silently` arguments to [`send_mail()`](../../topics/email/#django.core.mail.send_mail "django.core.mail.send_mail"), [`send_mass_mail()`](../../topics/email/#django.core.mail.send_mass_mail "django.core.mail.send_mass_mail"), [`mail_admins()`](../../topics/email/#django.core.mail.mail_admins "django.core.mail.mail_admins"), [`mail_managers()`](../../topics/email/#django.core.mail.mail_managers "django.core.mail.mail_managers"), and [`EmailMessage.send()`](../../topics/email/#django.core.mail.EmailMessage.send "django.core.mail.EmailMessage.send") can be replaced in several ways. Existing usage seems to have several different expectations for the behavior, many of which don’t match the actual (and email backend-dependent) implementation. Consider removing `fail_silently` entirely if there is not a specific need for it. Calls with `fail_silently=True` should be updated with one of these options, depending on the caller’s intent: * To send a message if email has been configured but avoid raising an error if it hasn’t (e.g., in a reusable library), wrap the send call in `try:` / `except mail.MailerDoesNotExist: pass`. * To ignore *all* exceptions (e.g., to avoid cascading failures in an error handler that sends mail), wrap the send call in `try:` / `except Exception: pass`. * To ignore only SMTP-related errors, wrap the send call in `try` / `except OSError: pass`. Note that this ignores both transient network glitches *and* SMTP configuration problems (just like the existing SMTP email backend `fail_silently` implementation). * To ignore end user typos in `to` addresses and other delivery problems, remove the `fail_silently` argument. Recipient errors are not generally detected at send time, so using `fail_silently` for this purpose doesn’t accomplish anything and could mask other problems like configuration errors. (In *local delivery* configurations, SMTP servers may report some recipient errors at send time. If you are using `fail_silently` specifically to ignore those errors, consider instead intercepting [`SMTPRecipientsRefused`](https://docs.python.org/3/library/smtplib.html#smtplib.SMTPRecipientsRefused "(in Python v3.15)") and/or [`SMTPResponseException`](https://docs.python.org/3/library/smtplib.html#smtplib.SMTPResponseException "(in Python v3.15)")s with particular `smtp_code` values as a more precise filter.) * To create an email configuration that ignores certain backend-dependent errors and reuse it for multiple sending operations, create a custom [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration with `"fail_silently": True` in the [`"OPTIONS"`](../../ref/settings/#std-setting-MAILERS-OPTIONS), then refer to that configuration with `using` in the send call. Calls with `fail_silently=False` should be updated to remove the `fail_silently` arg, as that is the default. If you use [`AdminEmailHandler`](../../ref/logging/#django.utils.log.AdminEmailHandler "django.utils.log.AdminEmailHandler") or [`BrokenLinkEmailsMiddleware`](../../ref/middleware/#django.middleware.common.BrokenLinkEmailsMiddleware "django.middleware.common.BrokenLinkEmailsMiddleware") and rely on their previous fail-silent behavior, see [Ignoring transient failures in error reporting](#migrating-to-mailers-error-reporting). ## Migrating custom email backends[¶](#migrating-custom-email-backends "Link to this heading") Custom `EmailBackend` implementations may need to be updated for compatibility with mailers. * In the backend’s `__init__()` method, accept explicit keyword arguments for all configuration options that can come from [`"OPTIONS"`](../../ref/settings/#std-setting-MAILERS-OPTIONS). Backends that use custom settings for configuration can continue to do so (or not, as they choose), but keyword arguments should take precedence over settings. * Accept variable `**kwargs` and pass them to superclass init. (This will include a new `alias` argument which must be passed to the superclass.) Ensure that any `**kwargs` used by the backend are *not* passed to superclass init, as that would generate an `InvalidMailer` error for unknown OPTIONS. * Backends must now handle `fail_silently` themselves, if they want to support it. There is no requirement to support `fail_silently`, and backends that don’t offer it should eliminate that keyword argument. (Do not pass an explicit `fail_silently` arg to superclass init.) * Do not accept variable positional `*args` or pass them to superclass init. The `BaseEmailBackend` superclass now initializes an `alias` attribute. This is useful for error messages (e.g., `raise InvalidMailer(f"Bad host {host}", alias=self.alias)`), but should not be used for accessing `settings.MAILERS` directly. All OPTIONS for a mailer configuration are passed to backend init as keyword arguments. For reusable libraries that want to support compatibility with deprecated mail functions and settings, or that support older Django versions: * A backend can detect it is being initialized without [`MAILERS`](../../ref/settings/#std-setting-MAILERS) by checking if `self.alias is None`. (Django’s built-in backends check this to decide whether deprecated settings should be used.) Libraries supporting older Django versions will need to use `getattr(self, "alias", None)`. * Backends that borrow Django’s SMTP email settings like [`EMAIL_HOST`](../../ref/settings/#std-setting-EMAIL_HOST) must *not* try to access them when [`MAILERS`](../../ref/settings/#std-setting-MAILERS) is in use (`self.alias is not None`), as this will cause a “not available when MAILERS is defined” `AttributeError`. * Libraries supporting multiple Django versions can identify support for mailers with either `hasattr(django.core.mail, "mailers")` or `django.VERSION >= (6, 1)`. ## Replacing `auth_user` and `auth_password`[¶](#replacing-auth-user-and-auth-password "Link to this heading") The deprecated `auth_user` and `auth_password` arguments to [`send_mail()`](../../topics/email/#django.core.mail.send_mail "django.core.mail.send_mail") and [`send_mass_mail()`](../../topics/email/#django.core.mail.send_mass_mail "django.core.mail.send_mass_mail") can be replaced by defining a custom [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration with `"username"` and `"password"` [`"OPTIONS"`](../../ref/settings/#std-setting-MAILERS-OPTIONS), and refer to that configuration with the `using` argument when sending mail. For example, to upgrade: ``` mail.send_mail(..., auth_user="admin", auth_password="admin-password") ``` Add a custom [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration in your settings: ``` MAILERS = { # Existing default configuration. "default": { "OPTIONS": { "host": "smtp.example.com", "username": "default-user", "password": "default-password", }, }, # Duplicate the default configuration, changing the auth. "admin-config": { "OPTIONS": { "host": "smtp.example.com", "username": "admin", "password": "admin-password", }, }, } ``` And then refer to it when sending: ``` mail.send_mail(..., using="admin-config") ``` ## Updating AdminEmailHandler `email_backend`[¶](#updating-adminemailhandler-email-backend "Link to this heading") The deprecated `email_backend` argument to the logging [`AdminEmailHandler`](../../ref/logging/#django.utils.log.AdminEmailHandler "django.utils.log.AdminEmailHandler") can be replaced with a custom [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration, referring to it with the `using` argument. For example, if your settings include: ``` LOGGING = { # ... "handlers": { "mail_admins": { "class": "django.utils.log.AdminEmailHandler", "email_backend": "third.party.EmailBackend", }, }, # ... } ``` Replace that with: ``` LOGGING = { # ... "handlers": { "mail_admins": { "class": "django.utils.log.AdminEmailHandler", "using": "admin-logging", # defined in MAILERS }, }, # ... } MAILERS = { "default": {...}, "admin-logging": { "BACKEND": "third.party.EmailBackend", }, } ``` ## Ignoring transient failures in error reporting[¶](#ignoring-transient-failures-in-error-reporting "Link to this heading") Django includes two features that report errors via email: [`AdminEmailHandler`](../../ref/logging/#django.utils.log.AdminEmailHandler "django.utils.log.AdminEmailHandler") and [`BrokenLinkEmailsMiddleware`](../../ref/middleware/#django.middleware.common.BrokenLinkEmailsMiddleware "django.middleware.common.BrokenLinkEmailsMiddleware"). In earlier releases, those features used the deprecated [fail\_silently](#migrating-to-mailers-fail-silently) argument. Starting in Django 2028 – or immediately once the [`MAILERS`](../../ref/settings/#std-setting-MAILERS) setting is defined – those features no longer use `fail_silently` so no longer ignore certain backend-specific errors. This may affect projects that use those features with an unreliable SMTP connection and rely on silently ignoring temporary network failures (and certain SMTP configuration errors). If you want to continue dropping error notification emails that cannot be sent, define a [`MAILERS`](../../ref/settings/#std-setting-MAILERS) configuration with the `"fail_silently"` option enabled for use by those error handlers: ``` MAILERS = { "default": {...}, "admin-logging": { "BACKEND": "django.core.mail.backends.smtp.EmailBackend", "OPTIONS": { # ... other SMTP options ... "fail_silently": True, }, }, } ``` To use this for [`AdminEmailHandler`](../../ref/logging/#django.utils.log.AdminEmailHandler "django.utils.log.AdminEmailHandler"), set the `"using"` option in the [`LOGGING`](../../ref/settings/#std-setting-LOGGING) config as shown in the previous section. To use this for [`BrokenLinkEmailsMiddleware`](../../ref/middleware/#django.middleware.common.BrokenLinkEmailsMiddleware "django.middleware.common.BrokenLinkEmailsMiddleware"), create a subclass that defines `using`, and then specify the path to that subclass in your [`MIDDLEWARE`](../../ref/settings/#std-setting-MIDDLEWARE) setting: ``` from django.middleware.common import BrokenLinkEmailsMiddleware class CustomBrokenLinkEmailsMiddleware(BrokenLinkEmailsMiddleware): using = "admin-logging" ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [Valerie Lanard donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Migrating email to mailers](#) * [Migrating settings](#migrating-settings) * [Reusable library readiness](#reusable-library-readiness) * [Solving “not available when MAILERS is defined” errors](#solving-not-available-when-mailers-is-defined-errors) * [Replacing `get_connection()` and `connection` arguments](#replacing-get-connection-and-connection-arguments) * [Replacing `fail_silently`](#replacing-fail-silently) * [Migrating custom email backends](#migrating-custom-email-backends) * [Replacing `auth_user` and `auth_password`](#replacing-auth-user-and-auth-password) * [Updating AdminEmailHandler `email_backend`](#updating-adminemailhandler-email-backend) * [Ignoring transient failures in error reporting](#ignoring-transient-failures-in-error-reporting) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.11.3/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.11.3/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.11.3/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.11.3/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.11.3/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.11.3/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.11.3/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.11.3/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.11.3/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.11.3/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.11.3/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.11.3/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.11.3/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.11.3/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.11.3/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.11.3/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.11.3/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.11.3/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.11.3/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.11.3/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.11.3/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.11.3/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.11.3/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.11.3/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.11.3/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.11.3/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.11.3/) - [**](#top) # Django 1.11.3 release notes[¶](#django-1-11-3-release-notes "Link to this heading") *July 1, 2017* Django 1.11.3 fixes several bugs in 1.11.2. ## Bugfixes[¶](#bugfixes "Link to this heading") * Removed an incorrect deprecation warning about a missing `renderer` argument if a `Widget.render()` method accepts `**kwargs` ([#28265](https://code.djangoproject.com/ticket/28265)). * Fixed a regression causing `Model.__init__()` to crash if a field has an instance only descriptor ([#28269](https://code.djangoproject.com/ticket/28269)). * Fixed an incorrect `DisallowedModelAdminLookup` exception when using a nested reverse relation in `list_filter` ([#28262](https://code.djangoproject.com/ticket/28262)). * Fixed admin’s `FieldListFilter.get_queryset()` crash on invalid input ([#28202](https://code.djangoproject.com/ticket/28202)). * Fixed invalid HTML for a required `AdminFileWidget` ([#28278](https://code.djangoproject.com/ticket/28278)). * Fixed model initialization to set the name of class-based model indexes for models that only inherit `models.Model` ([#28282](https://code.djangoproject.com/ticket/28282)). * Fixed crash in admin’s inlines when a model has an inherited non-editable primary key ([#27967](https://code.djangoproject.com/ticket/27967)). * Fixed `QuerySet.union()`, `intersection()`, and `difference()` when combining with an `EmptyQuerySet` ([#28293](https://code.djangoproject.com/ticket/28293)). * Prevented `Paginator`’s unordered object list warning from evaluating a `QuerySet` ([#28284](https://code.djangoproject.com/ticket/28284)). * Fixed the value of `redirect_field_name` in `LoginView`’s template context. It’s now an empty string (as it is for the original function-based `login()` view) if the corresponding parameter isn’t sent in a request (in particular, when the login page is accessed directly) ([#28229](https://code.djangoproject.com/ticket/28229)). * Prevented attribute values in the `django/forms/widgets/attrs.html` template from being localized so that numeric attributes (e.g. `max` and `min`) of `NumberInput` work correctly ([#28303](https://code.djangoproject.com/ticket/28303)). * Removed casting of the option value to a string in the template context of the `CheckboxSelectMultiple`, `NullBooleanSelect`, `RadioSelect`, `SelectMultiple`, and `Select` widgets ([#28176](https://code.djangoproject.com/ticket/28176)). In Django 1.11.1, casting was added in Python to avoid localization of numeric values in Django templates, but this made some use cases more difficult. Casting is now done in the template using the `|stringformat:'s'` filter. * Prevented a primary key alteration from adding a foreign key constraint if `db_constraint=False` ([#28298](https://code.djangoproject.com/ticket/28298)). * Fixed `UnboundLocalError` crash in `RenameField` with nonexistent field ([#28350](https://code.djangoproject.com/ticket/28350)). * Fixed a regression preventing a model field’s `limit_choices_to` from being evaluated when a `ModelForm` is instantiated ([#28345](https://code.djangoproject.com/ticket/28345)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Zaur Labs ApS donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.11.3 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/ref/contrib/humanize/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/humanize/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/contrib/humanize/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/contrib/humanize/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/contrib/humanize/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/contrib/humanize/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/contrib/humanize/) - [it](https://docs.djangoproject.com/it/6.1/ref/contrib/humanize/) - [id](https://docs.djangoproject.com/id/6.1/ref/contrib/humanize/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/contrib/humanize/) - [es](https://docs.djangoproject.com/es/6.1/ref/contrib/humanize/) - [el](https://docs.djangoproject.com/el/6.1/ref/contrib/humanize/) * * [dev](https://docs.djangoproject.com/en/dev/ref/contrib/humanize/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/contrib/humanize/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/contrib/humanize/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/contrib/humanize/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/contrib/humanize/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/contrib/humanize/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/contrib/humanize/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/contrib/humanize/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/contrib/humanize/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/contrib/humanize/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/contrib/humanize/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/contrib/humanize/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/contrib/humanize/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/contrib/humanize/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/contrib/humanize/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/contrib/humanize/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/contrib/humanize/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/contrib/humanize/) - [**](#top) # `django.contrib.humanize`[¶](#module-django.contrib.humanize "Link to this heading") A set of Django template filters useful for adding a “human touch” to data. To activate these filters, add `'django.contrib.humanize'` to your [`INSTALLED_APPS`](../../settings/#std-setting-INSTALLED_APPS) setting. Once you’ve done that, use `{% load humanize %}` in a template, and you’ll have access to the following filters. ## `apnumber`[¶](#apnumber "Link to this heading") For numbers 1-9, returns the number spelled out. Otherwise, returns the number. This follows Associated Press style. Examples: * `1` becomes `one`. * `2` becomes `two`. * `10` becomes `10`. You can pass in either an integer or a string representation of an integer. ## `intcomma`[¶](#intcomma "Link to this heading") Converts an integer or float (or a string representation of either) to a string containing commas every three digits. Examples: * `4500` becomes `4,500`. * `4500.2` becomes `4,500.2`. * `45000` becomes `45,000`. * `450000` becomes `450,000`. * `4500000` becomes `4,500,000`. [Format localization](../../../topics/i18n/formatting/) will be respected if enabled, e.g. with the `'de'` language: * `45000` becomes `'45.000'`. * `450000` becomes `'450.000'`. ## `intword`[¶](#intword "Link to this heading") Converts a large integer (or a string representation of an integer) to a friendly text representation. Translates `1.0` as a singular phrase and all other numeric values as plural, this may be incorrect for some languages. Works best for numbers over 1 million. Examples: * `1000000` becomes `1.0 million`. * `1200000` becomes `1.2 million`. * `1200000000` becomes `1.2 billion`. * `-1200000000` becomes `-1.2 billion`. Values up to 10^100 (Googol) are supported. [Format localization](../../../topics/i18n/formatting/) will be respected if enabled, e.g. with the `'de'` language: * `1000000` becomes `'1,0 Million'`. * `1200000` becomes `'1,2 Millionen'`. * `1200000000` becomes `'1,2 Milliarden'`. * `-1200000000` becomes `'-1,2 Milliarden'`. ## `naturalday`[¶](#naturalday "Link to this heading") For dates that are the current day or within one day, return “today”, “tomorrow” or “yesterday”, as appropriate. Otherwise, format the date using the passed in format string. **Argument:** Date formatting string as described in the [`date`](../../templates/builtins/#std-templatefilter-date) tag. Examples (when ‘today’ is 17 Feb 2007): * `16 Feb 2007` becomes `yesterday`. * `17 Feb 2007` becomes `today`. * `18 Feb 2007` becomes `tomorrow`. * Any other day is formatted according to given argument or the [`DATE_FORMAT`](../../settings/#std-setting-DATE_FORMAT) setting if no argument is given. ## `naturaltime`[¶](#naturaltime "Link to this heading") For datetime values, returns a string representing how many seconds, minutes or hours ago it was – falling back to the [`timesince`](../../templates/builtins/#std-templatefilter-timesince) format if the value is more than a day old. In case the datetime value is in the future the return value will automatically use an appropriate phrase. Examples (when ‘now’ is 17 Feb 2007 16:30:00): * `17 Feb 2007 16:30:00` becomes `now`. * `17 Feb 2007 16:29:31` becomes `29 seconds ago`. * `17 Feb 2007 16:29:00` becomes `a minute ago`. * `17 Feb 2007 16:25:35` becomes `4 minutes ago`. * `17 Feb 2007 15:30:29` becomes `59 minutes ago`. * `17 Feb 2007 15:30:01` becomes `59 minutes ago`. * `17 Feb 2007 15:30:00` becomes `an hour ago`. * `17 Feb 2007 13:31:29` becomes `2 hours ago`. * `16 Feb 2007 13:31:29` becomes `1 day, 2 hours ago`. * `16 Feb 2007 13:30:01` becomes `1 day, 2 hours ago`. * `16 Feb 2007 13:30:00` becomes `1 day, 3 hours ago`. * `17 Feb 2007 16:30:30` becomes `30 seconds from now`. * `17 Feb 2007 16:30:29` becomes `29 seconds from now`. * `17 Feb 2007 16:31:00` becomes `a minute from now`. * `17 Feb 2007 16:34:35` becomes `4 minutes from now`. * `17 Feb 2007 17:30:29` becomes `an hour from now`. * `17 Feb 2007 18:31:29` becomes `2 hours from now`. * `18 Feb 2007 16:31:29` becomes `1 day from now`. * `26 Feb 2007 18:31:29` becomes `1 week, 2 days from now`. ## `ordinal`[¶](#ordinal "Link to this heading") Converts an integer to its ordinal as a string. Examples: * `1` becomes `1st`. * `2` becomes `2nd`. * `3` becomes `3rd`. You can pass in either an integer or a string representation of an integer. Negative integers are returned unchanged. [**Back to Top](#top) ## Additional Information ### Support Django! * [Hannes Ljungberg donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [`django.contrib.humanize`](#) * [`apnumber`](#apnumber) * [`intcomma`](#intcomma) * [`intword`](#intword) * [`naturalday`](#naturalday) * [`naturaltime`](#naturaltime) * [`ordinal`](#ordinal) ---- url: https://docs.djangoproject.com/en/6.1/glossary/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/glossary/) - [sv](https://docs.djangoproject.com/sv/6.1/glossary/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/glossary/) - [pl](https://docs.djangoproject.com/pl/6.1/glossary/) - [ko](https://docs.djangoproject.com/ko/6.1/glossary/) - [ja](https://docs.djangoproject.com/ja/6.1/glossary/) - [it](https://docs.djangoproject.com/it/6.1/glossary/) - [id](https://docs.djangoproject.com/id/6.1/glossary/) - [fr](https://docs.djangoproject.com/fr/6.1/glossary/) - [es](https://docs.djangoproject.com/es/6.1/glossary/) - [el](https://docs.djangoproject.com/el/6.1/glossary/) * * [dev](https://docs.djangoproject.com/en/dev/glossary/) * [6.0](https://docs.djangoproject.com/en/6.0/glossary/) * [5.2](https://docs.djangoproject.com/en/5.2/glossary/) * [5.1](https://docs.djangoproject.com/en/5.1/glossary/) * [5.0](https://docs.djangoproject.com/en/5.0/glossary/) * [4.2](https://docs.djangoproject.com/en/4.2/glossary/) * [4.1](https://docs.djangoproject.com/en/4.1/glossary/) * [4.0](https://docs.djangoproject.com/en/4.0/glossary/) * [3.2](https://docs.djangoproject.com/en/3.2/glossary/) * [3.1](https://docs.djangoproject.com/en/3.1/glossary/) * [3.0](https://docs.djangoproject.com/en/3.0/glossary/) * [2.2](https://docs.djangoproject.com/en/2.2/glossary/) * [2.1](https://docs.djangoproject.com/en/2.1/glossary/) * [2.0](https://docs.djangoproject.com/en/2.0/glossary/) * [1.11](https://docs.djangoproject.com/en/1.11/glossary/) * [1.10](https://docs.djangoproject.com/en/1.10/glossary/) * [1.9](https://docs.djangoproject.com/en/1.9/glossary/) * [1.8](https://docs.djangoproject.com/en/1.8/glossary/) - [**](#top) # Glossary[¶](#glossary "Link to this heading") * concrete model[¶](#term-concrete-model "Link to this term") A non-abstract ([`abstract=False`](../ref/models/options/#django.db.models.Options.abstract "django.db.models.Options.abstract")) model. * field[¶](#term-field "Link to this term") An attribute on a [model](#term-model); a given field usually maps directly to a single database column. See [Models](../topics/db/models/). * generic view[¶](#term-generic-view "Link to this term") A higher-order [view](#term-view) function that provides an abstract/generic implementation of a common idiom or pattern found in view development. See [Class-based views](../topics/class-based-views/). * model[¶](#term-model "Link to this term") Models store your application’s data. See [Models](../topics/db/models/). * MTV[¶](#term-MTV "Link to this term") “Model-template-view”; a software pattern, similar in style to MVC, but a better description of the way Django does things. See [the FAQ entry](../faq/general/#faq-mtv). * MVC[¶](#term-MVC "Link to this term") [Model-view-controller](https://en.wikipedia.org/wiki/Model-view-controller); a software pattern. Django [follows MVC to some extent](../faq/general/#faq-mtv). * project[¶](#term-project "Link to this term") A Python package – i.e. a directory of code – that contains all the settings for an instance of Django. This would include database configuration, Django-specific options and application-specific settings. * property[¶](#term-property "Link to this term") Also known as “managed attributes”, and a feature of Python since version 2.2. This is a neat way to implement attributes whose usage resembles attribute access, but whose implementation uses method calls. See [`property`](https://docs.python.org/3/builtins/functions.html#property "(in Python v3.15)"). * queryset[¶](#term-queryset "Link to this term") An object representing some set of rows to be fetched from the database. See [Making queries](../topics/db/queries/). * slug[¶](#term-slug "Link to this term") A short label for something, containing only letters, numbers, underscores or hyphens. They’re generally used in URLs. For example, in a typical blog entry URL: ``` https://www.djangoproject.com/weblog/2008/apr/12/spring/ ``` the last bit (`spring`) is the slug. * template[¶](#term-template "Link to this term") A chunk of text that acts as formatting for representing data. A template helps to abstract the presentation of data from the data itself. See [Templates](../topics/templates/). * view[¶](#term-view "Link to this term") A function responsible for rendering a page. [**Back to Top](#top) ## Additional Information ### Support Django! * [David Winterbottom donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Glossary](#) ---- url: https://docs.djangoproject.com/en/6.1/ref/contrib/gis/forms-api/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/gis/forms-api/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/contrib/gis/forms-api/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/contrib/gis/forms-api/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/contrib/gis/forms-api/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/contrib/gis/forms-api/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/contrib/gis/forms-api/) - [it](https://docs.djangoproject.com/it/6.1/ref/contrib/gis/forms-api/) - [id](https://docs.djangoproject.com/id/6.1/ref/contrib/gis/forms-api/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/contrib/gis/forms-api/) - [es](https://docs.djangoproject.com/es/6.1/ref/contrib/gis/forms-api/) - [el](https://docs.djangoproject.com/el/6.1/ref/contrib/gis/forms-api/) * * [dev](https://docs.djangoproject.com/en/dev/ref/contrib/gis/forms-api/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/contrib/gis/forms-api/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/contrib/gis/forms-api/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/contrib/gis/forms-api/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/contrib/gis/forms-api/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/contrib/gis/forms-api/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/contrib/gis/forms-api/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/contrib/gis/forms-api/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/contrib/gis/forms-api/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/contrib/gis/forms-api/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/contrib/gis/forms-api/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/contrib/gis/forms-api/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/contrib/gis/forms-api/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/contrib/gis/forms-api/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/contrib/gis/forms-api/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/contrib/gis/forms-api/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/contrib/gis/forms-api/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/contrib/gis/forms-api/) - [**](#top) # GeoDjango Forms API[¶](#module-django.contrib.gis.forms "Link to this heading") GeoDjango provides some specialized form fields and widgets in order to visually display and edit geolocalized data on a map. By default, they use [OpenLayers](https://openlayers.org/)-powered maps, with a base WMS layer provided by [NASA](https://www.earthdata.nasa.gov/). ## Field arguments[¶](#field-arguments "Link to this heading") In addition to the regular [form field arguments](../../../forms/fields/#core-field-arguments), GeoDjango form fields take the following optional arguments. ### `srid`[¶](#srid "Link to this heading") * Field.srid[¶](#django.contrib.gis.forms.Field.srid "Link to this definition") This is the SRID code that the field value should be transformed to. For example, if the map widget SRID is different from the SRID more generally used by your application or database, the field will automatically convert input values into that SRID. ### `geom_type`[¶](#geom-type "Link to this heading") * Field.geom\_type[¶](#django.contrib.gis.forms.Field.geom_type "Link to this definition") You generally shouldn’t have to set or change that attribute which should be set up depending on the field class. It matches the OpenGIS standard geometry name. ### `max_geom_collections`[¶](#max-geom-collections "Link to this heading") * Field.max\_geom\_collections[¶](#django.contrib.gis.forms.Field.max_geom_collections "Link to this definition") The maximum number of geometry collections the field accepts before refusing to parse the input and raising a [`ValidationError`](../../../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError"). This guards against crashes in the underlying GEOS library when parsing deeply nested `GEOMETRYCOLLECTION` input. It defaults to `198`. The limit bounds the nesting depth for well-known text (WKT), well-known binary (WKB), and hex-encoded WKB. For GeoJSON, the limit is not applied at all, since GDAL parses that input type instead. Increase this value (or set to `None`) only if you must accept legitimately deep geometries, since doing so reduces protection against fatal errors. ## Form field classes[¶](#form-field-classes "Link to this heading") ### `GeometryField`[¶](#geometryfield "Link to this heading") * *class *GeometryField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/fields.py#L10)[¶](#django.contrib.gis.forms.GeometryField "Link to this definition") ### `PointField`[¶](#pointfield "Link to this heading") * *class *PointField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/fields.py#L131)[¶](#django.contrib.gis.forms.PointField "Link to this definition") ### `LineStringField`[¶](#linestringfield "Link to this heading") * *class *LineStringField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/fields.py#L139)[¶](#django.contrib.gis.forms.LineStringField "Link to this definition") ### `PolygonField`[¶](#polygonfield "Link to this heading") * *class *PolygonField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/fields.py#L147)[¶](#django.contrib.gis.forms.PolygonField "Link to this definition") ### `MultiPointField`[¶](#multipointfield "Link to this heading") * *class *MultiPointField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/fields.py#L135)[¶](#django.contrib.gis.forms.MultiPointField "Link to this definition") ### `MultiLineStringField`[¶](#multilinestringfield "Link to this heading") * *class *MultiLineStringField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/fields.py#L143)[¶](#django.contrib.gis.forms.MultiLineStringField "Link to this definition") ### `MultiPolygonField`[¶](#multipolygonfield "Link to this heading") * *class *MultiPolygonField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/fields.py#L151)[¶](#django.contrib.gis.forms.MultiPolygonField "Link to this definition") ### `GeometryCollectionField`[¶](#geometrycollectionfield "Link to this heading") * *class *GeometryCollectionField[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/fields.py#L127)[¶](#django.contrib.gis.forms.GeometryCollectionField "Link to this definition") ## Form widgets[¶](#module-django.contrib.gis.forms.widgets "Link to this heading") GeoDjango form widgets allow you to display and edit geographic data on a visual map. Note that none of the currently available widgets supports 3D geometries, hence geometry fields will fallback using a `Textarea` widget for such data. ### Widget attributes[¶](#widget-attributes "Link to this heading") GeoDjango widgets are template-based, so their attributes are mostly different from other Django widget attributes. * BaseGeometryWidget.base\_layer[¶](#django.contrib.gis.forms.widgets.BaseGeometryWidget.base_layer "Link to this definition") New in Django 6.0. A string that specifies the identifier for the default base map layer to be used by the corresponding JavaScript map widget. It is passed as part of the widget options when rendering, allowing the `MapWidget` to determine which map tile provider or base layer to initialize (default is `None`). - BaseGeometryWidget.geom\_type[¶](#django.contrib.gis.forms.widgets.BaseGeometryWidget.geom_type "Link to this definition") The OpenGIS geometry type, generally set by the form field. * BaseGeometryWidget.map\_srid[¶](#django.contrib.gis.forms.widgets.BaseGeometryWidget.map_srid "Link to this definition") SRID code used by the map (default is 4326). - BaseGeometryWidget.display\_raw[¶](#django.contrib.gis.forms.widgets.BaseGeometryWidget.display_raw "Link to this definition") Boolean value specifying if a textarea input showing the serialized representation of the current geometry is visible, mainly for debugging purposes (default is `False`). * BaseGeometryWidget.supports\_3d[¶](#django.contrib.gis.forms.widgets.BaseGeometryWidget.supports_3d "Link to this definition") Indicates if the widget supports edition of 3D data (default is `False`). - BaseGeometryWidget.template\_name[¶](#django.contrib.gis.forms.widgets.BaseGeometryWidget.template_name "Link to this definition") The template used to render the map widget. You can pass widget attributes in the same manner that for any other Django widget. For example: ``` from django.contrib.gis import forms class MyGeoForm(forms.Form): point = forms.PointField(widget=forms.OSMWidget(attrs={"display_raw": True})) ``` ### Widget classes[¶](#widget-classes "Link to this heading") `BaseGeometryWidget` * *class *BaseGeometryWidget[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/widgets.py#L13)[¶](#django.contrib.gis.forms.widgets.BaseGeometryWidget "Link to this definition") This is an abstract base widget containing the logic needed by subclasses. You cannot directly use this widget for a geometry field. Note that the rendering of GeoDjango widgets is based on a base layer name, identified by the [`base_layer`](#django.contrib.gis.forms.widgets.BaseGeometryWidget.base_layer "django.contrib.gis.forms.widgets.BaseGeometryWidget.base_layer") class attribute. `OpenLayersWidget` * *class *OpenLayersWidget[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/widgets.py#L75)[¶](#django.contrib.gis.forms.widgets.OpenLayersWidget "Link to this definition") This is the default widget used by all GeoDjango form fields. Attributes are: * base\_layer[¶](#django.contrib.gis.forms.widgets.OpenLayersWidget.base_layer "Link to this definition") New in Django 6.0. `nasaWorldview` - template\_name[¶](#django.contrib.gis.forms.widgets.OpenLayersWidget.template_name "Link to this definition") `gis/openlayers.html`. * map\_srid[¶](#django.contrib.gis.forms.widgets.OpenLayersWidget.map_srid "Link to this definition") `3857` `OpenLayersWidget` and [`OSMWidget`](#django.contrib.gis.forms.widgets.OSMWidget "django.contrib.gis.forms.widgets.OSMWidget") include the `ol.js` and `ol.css` files hosted on the `cdn.jsdelivr.net` content-delivery network. These files can be overridden by subclassing the widget and setting the `js` and `css` properties of the inner `Media` class (see [Assets as a static definition](../../../../topics/forms/media/#assets-as-a-static-definition)). External assets with CSP When [`ContentSecurityPolicyMiddleware`](../../../middleware/#django.middleware.csp.ContentSecurityPolicyMiddleware "django.middleware.csp.ContentSecurityPolicyMiddleware") is enabled, the default OpenLayers CDN assets (`ol.js` and `ol.css`) will be blocked unless explicitly allowed. This can be addressed in one of two ways: **serve assets locally** by subclassing the widget and provide local copies of the JavaScript and CSS files, or **allow the CDN in the CSP policy**. For example, to allow the default NASA Worldview base layer (replace `x.y.z` with the actual version): ``` from django.utils.csp import CSP SECURE_CSP = { "default-src": [CSP.SELF], "script-src": [CSP.SELF, "https://cdn.jsdelivr.net/npm/ol@x.y.z/dist/ol.js"], "style-src": [CSP.SELF, "https://cdn.jsdelivr.net/npm/ol@x.y.z/ol.css"], "img-src": [CSP.SELF, "https://*.earthdata.nasa.gov"], } ``` `OSMWidget` * *class *OSMWidget[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/forms/widgets.py#L103)[¶](#django.contrib.gis.forms.widgets.OSMWidget "Link to this definition") This widget specialized [`OpenLayersWidget`](#django.contrib.gis.forms.widgets.OpenLayersWidget "django.contrib.gis.forms.widgets.OpenLayersWidget") and uses an OpenStreetMap base layer to display geographic objects on. Attributes are: * base\_layer[¶](#django.contrib.gis.forms.widgets.OSMWidget.base_layer "Link to this definition") New in Django 6.0. `osm` - default\_lat[¶](#django.contrib.gis.forms.widgets.OSMWidget.default_lat "Link to this definition") * default\_lon[¶](#django.contrib.gis.forms.widgets.OSMWidget.default_lon "Link to this definition") The default center latitude and longitude are `47` and `5`, respectively, which is a location in eastern France. - default\_zoom[¶](#django.contrib.gis.forms.widgets.OSMWidget.default_zoom "Link to this definition") The default map zoom is `12`. The [`OpenLayersWidget`](#django.contrib.gis.forms.widgets.OpenLayersWidget "django.contrib.gis.forms.widgets.OpenLayersWidget") note about using external assets also applies here. See also this [FAQ answer](https://help.openstreetmap.org/questions/10920/how-to-embed-a-map-in-my-https-site) about `https` access to map tiles. OpenStreetMap tiles with CSP This widget uses OpenStreetMap tiles instead of NASA Worldview. If [Content Security Policy](../../../../topics/security/#security-csp) enabled, both the OpenLayers CDN resources (as required by [`OpenLayersWidget`](#django.contrib.gis.forms.widgets.OpenLayersWidget "django.contrib.gis.forms.widgets.OpenLayersWidget")) and the OpenStreetMap tile servers must be allowed: ``` from django.utils.csp import CSP SECURE_CSP = { # other directives "img-src": [CSP.SELF, "https://tile.openstreetmap.org"], } ``` Changed in Django 6.0: The `OSMWidget` no longer uses a custom template. Consequently, the `gis/openlayers-osm.html` template was removed. ### Customizing the base layer used in OpenLayers-based widgets[¶](#customizing-the-base-layer-used-in-openlayers-based-widgets "Link to this heading") New in Django 6.0. To customize the base layer displayed in OpenLayers-based geometry widgets, define a new layer builder in a custom JavaScript file. For example: `path-to-file.js`[¶](#id1 "Link to this code")** ``` MapWidget.layerBuilder.custom_layer_name = function () { // Return an OpenLayers layer instance. return new ol.layer.Tile({source: new ol.source.()}); }; ``` Then, subclass a standard geometry widget and set the `base_layer`: ``` from django.contrib.gis.forms.widgets import OpenLayersWidget class YourCustomWidget(OpenLayersWidget): base_layer = "custom_layer_name" class Media: js = ["path-to-file.js"] ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [Assem Chelli donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [GeoDjango Forms API](#) * [Field arguments](#field-arguments) * [`srid`](#srid) * [`geom_type`](#geom-type) * [`max_geom_collections`](#max-geom-collections) * [Form field classes](#form-field-classes) * [`GeometryField`](#geometryfield) * [`PointField`](#pointfield) * [`LineStringField`](#linestringfield) * [`PolygonField`](#polygonfield) * [`MultiPointField`](#multipointfield) * [`MultiLineStringField`](#multilinestringfield) * [`MultiPolygonField`](#multipolygonfield) * [`GeometryCollectionField`](#geometrycollectionfield) * [Form widgets](#module-django.contrib.gis.forms.widgets) * [Widget attributes](#widget-attributes) * [Widget classes](#widget-classes) * [Customizing the base layer used in OpenLayers-based widgets](#customizing-the-base-layer-used-in-openlayers-based-widgets) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.11.25/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.11.25/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.11.25/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.11.25/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.11.25/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.11.25/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.11.25/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.11.25/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.11.25/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.11.25/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.11.25/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.11.25/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.11.25/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.11.25/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.11.25/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.11.25/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.11.25/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.11.25/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.11.25/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.11.25/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.11.25/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.11.25/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.11.25/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.11.25/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.11.25/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.11.25/) - [**](#top) # Django 1.11.25 release notes[¶](#django-1-11-25-release-notes "Link to this heading") *October 1, 2019* Django 1.11.25 fixes a regression in 1.11.23. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a crash when filtering with a `Subquery()` annotation of a queryset containing `django.contrib.postgres.fields.JSONField` or [`HStoreField`](../../ref/contrib/postgres/fields/#django.contrib.postgres.fields.HStoreField "django.contrib.postgres.fields.HStoreField") ([#30769](https://code.djangoproject.com/ticket/30769)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Garage Door Nation donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.11.25 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.4.21/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.4.21/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.4.21/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.4.21/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.4.21/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.4.21/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.4.21/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.4.21/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.4.21/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.4.21/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.4.21/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.4.21/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.4.21/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.4.21/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.4.21/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.4.21/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.4.21/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.4.21/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.4.21/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.4.21/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.4.21/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.4.21/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.4.21/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.4.21/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.4.21/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.4.21/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.4.21/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.4.21/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.4.21/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.4.21/) - [**](#top) # Django 1.4.21 release notes[¶](#django-1-4-21-release-notes "Link to this heading") *July 8, 2015* Django 1.4.21 fixes several security issues in 1.4.20. ## Denial-of-service possibility by filling session store[¶](#denial-of-service-possibility-by-filling-session-store "Link to this heading") In previous versions of Django, the session backends created a new empty record in the session storage anytime `request.session` was accessed and there was a session key provided in the request cookies that didn’t already have a session record. This could allow an attacker to easily create many new session records simply by sending repeated requests with unknown session keys, potentially filling up the session store or causing other users’ session records to be evicted. The built-in session backends now create a session record only if the session is actually modified; empty session records are not created. Thus this potential DoS is now only possible if the site chooses to expose a session-modifying view to anonymous users. As each built-in session backend was fixed separately (rather than a fix in the core sessions framework), maintainers of third-party session backends should check whether the same vulnerability is present in their backend and correct it if so. ## Header injection possibility since validators accept newlines in input[¶](#header-injection-possibility-since-validators-accept-newlines-in-input "Link to this heading") Some of Django’s built-in validators ([`EmailValidator`](../../ref/validators/#django.core.validators.EmailValidator "django.core.validators.EmailValidator"), most seriously) didn’t prohibit newline characters (due to the usage of `$` instead of `\Z` in the regular expressions). If you use values with newlines in HTTP response or email headers, you can suffer from header injection attacks. Django itself isn’t vulnerable because [`HttpResponse`](../../ref/request-response/#django.http.HttpResponse "django.http.HttpResponse") and the mail sending utilities in [`django.core.mail`](../../topics/email/#module-django.core.mail "django.core.mail: Helpers to send email.") prohibit newlines in HTTP and SMTP headers, respectively. While the validators have been fixed in Django, if you’re creating HTTP responses or email messages in other ways, it’s a good idea to ensure that those methods prohibit newlines as well. You might also want to validate that any existing data in your application doesn’t contain unexpected newlines. [`validate_ipv4_address()`](../../ref/validators/#django.core.validators.validate_ipv4_address "django.core.validators.validate_ipv4_address"), [`validate_slug()`](../../ref/validators/#django.core.validators.validate_slug "django.core.validators.validate_slug"), and [`URLValidator`](../../ref/validators/#django.core.validators.URLValidator "django.core.validators.URLValidator") and their usage in the corresponding form fields `GenericIPAddresseField`, `IPAddressField`, `SlugField`, and `URLField` are also affected. The undocumented, internally unused `validate_integer()` function is now stricter as it validates using a regular expression instead of simply casting the value using `int()` and checking if an exception was raised. [**Back to Top](#top) ## Additional Information ### Support Django! * [Alex Gaynor donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.4.21 release notes](#) * [Denial-of-service possibility by filling session store](#denial-of-service-possibility-by-filling-session-store) * [Header injection possibility since validators accept newlines in input](#header-injection-possibility-since-validators-accept-newlines-in-input) ---- url: https://docs.djangoproject.com/en/6.1/releases/2.2.23/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/2.2.23/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/2.2.23/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/2.2.23/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/2.2.23/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/2.2.23/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/2.2.23/) - [it](https://docs.djangoproject.com/it/6.1/releases/2.2.23/) - [id](https://docs.djangoproject.com/id/6.1/releases/2.2.23/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/2.2.23/) - [es](https://docs.djangoproject.com/es/6.1/releases/2.2.23/) - [el](https://docs.djangoproject.com/el/6.1/releases/2.2.23/) * * [dev](https://docs.djangoproject.com/en/dev/releases/2.2.23/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/2.2.23/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/2.2.23/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/2.2.23/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/2.2.23/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/2.2.23/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/2.2.23/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/2.2.23/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/2.2.23/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/2.2.23/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/2.2.23/) - [**](#top) # Django 2.2.23 release notes[¶](#django-2-2-23-release-notes "Link to this heading") *May 13, 2021* Django 2.2.23 fixes a regression in 2.2.21. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a regression in Django 2.2.21 where saving `FileField` would raise a `SuspiciousFileOperation` even when a custom [`upload_to`](../../ref/models/fields/#django.db.models.FileField.upload_to "django.db.models.FileField.upload_to") returns a valid file path ([#32718](https://code.djangoproject.com/ticket/32718)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Aktech Labs donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 2.2.23 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/2.1.8/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/2.1.8/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/2.1.8/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/2.1.8/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/2.1.8/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/2.1.8/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/2.1.8/) - [it](https://docs.djangoproject.com/it/6.1/releases/2.1.8/) - [id](https://docs.djangoproject.com/id/6.1/releases/2.1.8/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/2.1.8/) - [es](https://docs.djangoproject.com/es/6.1/releases/2.1.8/) - [el](https://docs.djangoproject.com/el/6.1/releases/2.1.8/) * * [dev](https://docs.djangoproject.com/en/dev/releases/2.1.8/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/2.1.8/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/2.1.8/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/2.1.8/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/2.1.8/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/2.1.8/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/2.1.8/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/2.1.8/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/2.1.8/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/2.1.8/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/2.1.8/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/2.1.8/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/2.1.8/) - [**](#top) # Django 2.1.8 release notes[¶](#django-2-1-8-release-notes "Link to this heading") *April 1, 2019* Django 2.1.8 fixes a bug in 2.1.7. ## Bugfixes[¶](#bugfixes "Link to this heading") * Prevented admin inlines for a `ManyToManyField`'s implicit through model from being editable if the user only has the view permission ([#30289](https://code.djangoproject.com/ticket/30289)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Fort, Holloway, & Rogers donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 2.1.8 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/ref/forms/validation/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/forms/validation/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/forms/validation/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/forms/validation/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/forms/validation/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/forms/validation/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/forms/validation/) - [it](https://docs.djangoproject.com/it/6.1/ref/forms/validation/) - [id](https://docs.djangoproject.com/id/6.1/ref/forms/validation/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/forms/validation/) - [es](https://docs.djangoproject.com/es/6.1/ref/forms/validation/) - [el](https://docs.djangoproject.com/el/6.1/ref/forms/validation/) * * [dev](https://docs.djangoproject.com/en/dev/ref/forms/validation/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/forms/validation/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/forms/validation/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/forms/validation/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/forms/validation/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/forms/validation/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/forms/validation/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/forms/validation/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/forms/validation/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/forms/validation/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/forms/validation/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/forms/validation/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/forms/validation/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/forms/validation/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/forms/validation/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/forms/validation/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/forms/validation/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/forms/validation/) - [**](#top) # Form and field validation[¶](#form-and-field-validation "Link to this heading") Form validation happens when the data is cleaned. If you want to customize this process, there are various places to make changes, each one serving a different purpose. Three types of cleaning methods are run during form processing. These are normally executed when you call the `is_valid()` method on a form. There are other things that can also trigger cleaning and validation (accessing the `errors` attribute or calling `full_clean()` directly), but normally they won’t be needed. In general, any cleaning method can raise `ValidationError` if there is a problem with the data it is processing, passing the relevant information to the `ValidationError` constructor. [See below](#raising-validation-error) for the best practice in raising `ValidationError`. If no `ValidationError` is raised, the method should return the cleaned (normalized) data as a Python object. Most validation can be done using [validators](#validators) - helpers that can be reused. Validators are functions (or callables) that take a single argument and raise `ValidationError` on invalid input. Validators are run after the field’s `to_python` and `validate` methods have been called. Validation of a form is split into several steps, which can be customized or overridden: * The `to_python()` method on a `Field` is the first step in every validation. It coerces the value to a correct datatype and raises `ValidationError` if that is not possible. This method accepts the raw value from the widget and returns the converted value. For example, a `FloatField` will turn the data into a Python `float` or raise a `ValidationError`. * The `validate()` method on a `Field` handles field-specific validation that is not suitable for a validator. It takes a value that has been coerced to a correct datatype and raises `ValidationError` on any error. This method does not return anything and shouldn’t alter the value. You should override it to handle validation logic that you can’t or don’t want to put in a validator. * The `run_validators()` method on a `Field` runs all of the field’s validators and aggregates all the errors into a single `ValidationError`. You shouldn’t need to override this method. * The `clean()` method on a `Field` subclass is responsible for running `to_python()`, `validate()`, and `run_validators()` in the correct order and propagating their errors. If, at any time, any of the methods raise `ValidationError`, the validation stops and that error is raised. This method returns the clean data, which is then inserted into the `cleaned_data` dictionary of the form. * The `clean_()` method is called on a form subclass – where `` is replaced with the name of the form field attribute. This method does any cleaning that is specific to that particular attribute, unrelated to the type of field that it is. This method is not passed any parameters. You will need to look up the value of the field in `self.cleaned_data` and remember that it will be a Python object at this point, not the original string submitted in the form (it will be in `cleaned_data` because the general field `clean()` method, above, has already cleaned the data once). For example, if you wanted to validate that the contents of a `CharField` called `serialnumber` was unique, `clean_serialnumber()` would be the right place to do this. You don’t need a specific field (it’s a `CharField`), but you want a formfield-specific piece of validation and, possibly, cleaning/normalizing the data. The return value of this method replaces the existing value in `cleaned_data`, so it must be the field’s value from `cleaned_data` (even if this method didn’t change it) or a new cleaned value. * The form subclass’s `clean()` method can perform validation that requires access to multiple form fields. This is where you might put in checks such as “if field `A` is supplied, field `B` must contain a valid email address”. This method can return a completely different dictionary if it wishes, which will be used as the `cleaned_data`. Since the field validation methods have been run by the time `clean()` is called, you also have access to the form’s `errors` attribute which contains all the errors raised by cleaning of individual fields. Note that any errors raised by your [`Form.clean()`](../api/#django.forms.Form.clean "django.forms.Form.clean") override will not be associated with any field in particular. They go into a special “field” (called `__all__`), which you can access via the [`non_field_errors()`](../api/#django.forms.Form.non_field_errors "django.forms.Form.non_field_errors") method if you need to. If you want to attach errors to a specific field in the form, you need to call [`add_error()`](../api/#django.forms.Form.add_error "django.forms.Form.add_error"). Also note that there are special considerations when overriding the `clean()` method of a `ModelForm` subclass. (see the [ModelForm documentation](../../../topics/forms/modelforms/#overriding-modelform-clean-method) for more information) These methods are run in the order given above, one field at a time. That is, for each field in the form (in the order they are declared in the form definition), the `Field.clean()` method (or its override) is run, then `clean_()`. Finally, once those two methods are run for every field, the [`Form.clean()`](../api/#django.forms.Form.clean "django.forms.Form.clean") method, or its override, is executed whether or not the previous methods have raised errors. Examples of each of these methods are provided below. As mentioned, any of these methods can raise a `ValidationError`. For any field, if the `Field.clean()` method raises a `ValidationError`, any field-specific cleaning method is not called. However, the cleaning methods for all remaining fields are still executed. ## Raising `ValidationError`[¶](#raising-validationerror "Link to this heading") In order to make error messages flexible and easy to override, consider the following guidelines: * Provide a descriptive error `code` to the constructor, to allow programmatic use (e.g. in tests) that will not vary with translations: ``` # Good ValidationError(_("Invalid value"), code="invalid") # Bad ValidationError(_("Invalid value")) ``` * Don’t coerce variables into the message; use placeholders and the `params` argument of the constructor: ``` # Good ValidationError( _("Invalid value: %(value)s"), params={"value": "42"}, ) # Bad ValidationError(_("Invalid value: %s") % value) ``` * Use mapping keys instead of positional formatting. This enables putting the variables in any order or omitting them altogether when rewriting the message: ``` # Good ValidationError( _("Invalid value: %(value)s"), params={"value": "42"}, ) # Bad ValidationError( _("Invalid value: %s"), params=("42",), ) ``` * Wrap the message with `gettext` to enable translation: ``` # Good ValidationError(_("Invalid value")) # Bad ValidationError("Invalid value") ``` Putting it all together: ``` raise ValidationError( _("Invalid value: %(value)s"), code="invalid", params={"value": "42"}, ) ``` Following these guidelines is particularly necessary if you write reusable forms, form fields, and model fields. While not recommended, if you are at the end of the validation chain (i.e. your form `clean()` method) and you know you will *never* need to override your error message you can still opt for the less verbose: ``` ValidationError(_("Invalid value: %s") % value) ``` The [`Form.errors.as_data()`](../api/#django.forms.Form.errors.as_data "django.forms.Form.errors.as_data") and [`Form.errors.as_json()`](../api/#django.forms.Form.errors.as_json "django.forms.Form.errors.as_json") methods greatly benefit from fully featured `ValidationError`s (with a `code` name and a `params` dictionary). ### Raising multiple errors[¶](#raising-multiple-errors "Link to this heading") If you detect multiple errors during a cleaning method and wish to signal all of them to the form submitter, it is possible to pass a list of errors to the `ValidationError` constructor. As above, it is recommended to pass a list of `ValidationError` instances with `code`s and `params` but a list of strings will also work: ``` # Good raise ValidationError( [ ValidationError(_("Error 1"), code="error1"), ValidationError(_("Error 2"), code="error2"), ] ) # Bad raise ValidationError( [ _("Error 1"), _("Error 2"), ] ) ``` ## Using validation in practice[¶](#using-validation-in-practice "Link to this heading") The previous sections explained how validation works in general for forms. Since it can sometimes be easier to put things into place by seeing each feature in use, here are a series of small examples that use each of the previous features. ### Using validators[¶](#using-validators "Link to this heading") Django’s form (and model) fields support use of utility functions and classes known as validators. A validator is a callable object or function that takes a value and returns nothing if the value is valid or raises a [`ValidationError`](../../exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") if not. These can be passed to a field’s constructor, via the field’s `validators` argument, or defined on the [`Field`](../fields/#django.forms.Field "django.forms.Field") class itself with the `default_validators` attribute. Validators can be used to validate values inside the field, let’s have a look at Django’s `SlugField`: ``` from django.core import validators from django.forms import CharField class SlugField(CharField): default_validators = [validators.validate_slug] ``` As you can see, `SlugField` is a `CharField` with a customized validator that validates that submitted text obeys to some character rules. This can also be done on field definition so: ``` slug = forms.SlugField() ``` is equivalent to: ``` slug = forms.CharField(validators=[validators.validate_slug]) ``` Common cases such as validating against an email or a regular expression can be handled using existing validator classes available in Django. For example, `validators.validate_slug` is an instance of a [`RegexValidator`](../../validators/#django.core.validators.RegexValidator "django.core.validators.RegexValidator") constructed with the first argument being the pattern: `^[-a-zA-Z0-9_]+\Z`. See the section on [writing validators](../../validators/) to see a list of what is already available and for an example of how to write a validator. ### Form field default cleaning[¶](#form-field-default-cleaning "Link to this heading") Let’s first create a custom form field that validates its input is a string containing comma-separated email addresses. The full class looks like this: ``` from django import forms from django.core.validators import validate_email class MultiEmailField(forms.Field): def to_python(self, value): """Normalize data to a list of strings.""" # Return an empty list if no input was given. if not value: return [] return value.split(",") def validate(self, value): """Check if value consists only of valid emails.""" # Use the parent's handling of required fields, etc. super().validate(value) for email in value: validate_email(email) ``` Every form that uses this field will have these methods run before anything else can be done with the field’s data. This is cleaning that is specific to this type of field, regardless of how it is subsequently used. Let’s create a `ContactForm` to demonstrate how you’d use this field: ``` class ContactForm(forms.Form): subject = forms.CharField(max_length=100) message = forms.CharField() contact_email = forms.EmailField() recipients = MultiEmailField() urgent = forms.BooleanField(required=False) ``` Use `MultiEmailField` like any other form field. When the `is_valid()` method is called on the form, the `MultiEmailField.clean()` method will be run as part of the cleaning process and it will, in turn, call the custom `to_python()` and `validate()` methods. ### Cleaning a specific field attribute[¶](#cleaning-a-specific-field-attribute "Link to this heading") Continuing on from the previous example, suppose that in our `ContactForm`, we want to make sure that the `recipients` field only contains addresses that are `@example.com`. This is validation that is specific to our form, so we don’t want to put it into the general `MultiEmailField` class. Instead, we write a cleaning method that operates on the `recipients` field, like so: ``` from django import forms from django.core.exceptions import ValidationError class ContactForm(forms.Form): # Everything as before. ... def clean_recipients(self): data = self.cleaned_data["recipients"] if not all(email.endswith("@example.com") for email in data): raise ValidationError("All recipients must be @example.com.") # Always return a value to use as the new cleaned data, even if # this method didn't change it. return data ``` ### Cleaning and validating fields that depend on each other[¶](#cleaning-and-validating-fields-that-depend-on-each-other "Link to this heading") Suppose we add another requirement to our contact form: if the `urgent` field is `True`, the `subject` must contain `"help"`. We are performing validation on more than one field at a time, so the form’s [`clean()`](../api/#django.forms.Form.clean "django.forms.Form.clean") method is a good spot to do this. Notice that we are talking about the `clean()` method on the form here, whereas earlier we were writing a `clean()` method on a field. It’s important to keep the field and form difference clear when working out where to validate things. Fields are single data points, forms are a collection of fields. By the time the form’s `clean()` method is called, all the individual field clean methods will have been run (the previous two sections), so `self.cleaned_data` will be populated with any data that has survived so far. So you also need to remember to allow for the fact that the fields you are wanting to validate might not have survived the initial individual field checks. There are two ways to report any errors from this step. Probably the most common method is to display the error at the top of the form. To create such an error, you can raise a `ValidationError` from the `clean()` method. For example: ``` from django import forms from django.core.exceptions import ValidationError class ContactForm(forms.Form): # Everything as before. ... def clean(self): cleaned_data = super().clean() urgent = cleaned_data.get("urgent") subject = cleaned_data.get("subject") if urgent and subject: # Only do something if both fields are valid so far. if "help" not in subject: raise ValidationError( "Must put 'help' in the subject for urgent requests." ) ``` In this code, if the validation error is raised, the form will display an error message at the top of the form (normally) describing the problem. Such errors are non-field errors, which are displayed in the template with `{{ form.non_field_errors }}`. The call to `super().clean()` in the example code ensures that any validation logic in parent classes is maintained. If your form inherits another that doesn’t return a `cleaned_data` dictionary in its `clean()` method (doing so is optional), then don’t assign `cleaned_data` to the result of the `super()` call and use `self.cleaned_data` instead: ``` def clean(self): super().clean() urgent = self.cleaned_data.get("urgent") ... ``` The second approach for reporting validation errors might involve assigning the error message to one of the fields. In this case, let’s assign an error message to both the “subject” and “urgent” rows in the form display. Be careful when doing this in practice, since it can lead to confusing form output. We’re showing what is possible here and leaving it up to you and your designers to work out what works effectively in your particular situation. Our new code (replacing the previous sample) looks like this: ``` from django import forms class ContactForm(forms.Form): # Everything as before. ... def clean(self): cleaned_data = super().clean() urgent = cleaned_data.get("urgent") subject = cleaned_data.get("subject") if urgent and subject and "help" not in subject: self.add_error( "subject", "Must put 'help' in the subject for urgent requests." ) self.add_error( "urgent", "Must not mark urgent unless 'help' is in the subject." ) ``` The second argument of `add_error()` can be a string, or preferably an instance of `ValidationError`. See [Raising ValidationError](#raising-validation-error) for more details. Note that `add_error()` automatically removes the field from `cleaned_data`. [**Back to Top](#top) ## Additional Information ### Support Django! * [Mikkel Munch Mortensen donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Form and field validation](#) * [Raising `ValidationError`](#raising-validationerror) * [Raising multiple errors](#raising-multiple-errors) * [Using validation in practice](#using-validation-in-practice) * [Using validators](#using-validators) * [Form field default cleaning](#form-field-default-cleaning) * [Cleaning a specific field attribute](#cleaning-a-specific-field-attribute) * [Cleaning and validating fields that depend on each other](#cleaning-and-validating-fields-that-depend-on-each-other) ---- url: https://docs.djangoproject.com/en/6.1/ref/csp/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/csp/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/csp/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/csp/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/csp/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/csp/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/csp/) - [it](https://docs.djangoproject.com/it/6.1/ref/csp/) - [id](https://docs.djangoproject.com/id/6.1/ref/csp/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/csp/) - [es](https://docs.djangoproject.com/es/6.1/ref/csp/) - [el](https://docs.djangoproject.com/el/6.1/ref/csp/) * * [dev](https://docs.djangoproject.com/en/dev/ref/csp/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/csp/) - [**](#top) # Content Security Policy[¶](#content-security-policy "Link to this heading") New in Django 6.0. Content Security Policy (CSP) is a web security standard that helps prevent content injection attacks by restricting the sources from which content can be loaded. It plays an important role in a comprehensive [security strategy](../../topics/security/#security-csp). For configuration instructions in a Django project, see the [Using CSP](../../howto/csp/#csp-config) documentation. For an HTTP guide about CSP, see the [MDN Guide on CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP). ## Overview[¶](#overview "Link to this heading") The [Content-Security-Policy specification](https://www.w3.org/TR/CSP3/) defines two complementary headers: * `Content-Security-Policy`: Enforces the CSP policy, blocking content that violates the defined directives. * `Content-Security-Policy-Report-Only`: Reports CSP violations without blocking content, allowing for non-intrusive testing. Each policy is composed of one or more directives and their values, which together instruct the browser on how to handle specific types of content. When the [`ContentSecurityPolicyMiddleware`](../middleware/#django.middleware.csp.ContentSecurityPolicyMiddleware "django.middleware.csp.ContentSecurityPolicyMiddleware") is enabled, Django automatically builds and attaches the appropriate headers to each response based on the configured [settings](#csp-settings), unless they have already been set by another layer. ## Settings[¶](#settings "Link to this heading") The [`ContentSecurityPolicyMiddleware`](../middleware/#django.middleware.csp.ContentSecurityPolicyMiddleware "django.middleware.csp.ContentSecurityPolicyMiddleware") is configured using the following settings: * [`SECURE_CSP`](../settings/#std-setting-SECURE_CSP): defines the **enforced Content Security Policy**. * [`SECURE_CSP_REPORT_ONLY`](../settings/#std-setting-SECURE_CSP_REPORT_ONLY): defines a **report-only Content Security Policy**. These settings can be used independently or together * Use [`SECURE_CSP`](../settings/#std-setting-SECURE_CSP) alone to enforce a policy that has already been tested and verified. * Use [`SECURE_CSP_REPORT_ONLY`](../settings/#std-setting-SECURE_CSP_REPORT_ONLY) on its own to evaluate a new policy without disrupting site behavior. This mode does not block violations, it only logs them. It’s useful for testing and monitoring, but provides no protection against active threats. * Use *both* to maintain an enforced baseline while experimenting with changes. Even for well-established policies, continuing to collect reports can help detect regressions, unexpected changes in behavior, or potential tampering in production environments. ## Policy violation reports[¶](#policy-violation-reports "Link to this heading") When a CSP violation occurs, browsers typically log details to the developer console, providing immediate feedback during development. To also receive these reports programmatically, the policy must include a [reporting directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#reporting_directives) such as `report-uri` that specifies where violation data should be sent. Django supports configuring these directives via the [`SECURE_CSP_REPORT_ONLY`](../settings/#std-setting-SECURE_CSP_REPORT_ONLY) settings, but reports will only be issued by the browser if the policy explicitly includes a valid reporting directive. Django does not provide built-in functionality to receive, store, or process violation reports. To collect and analyze them, you must implement your own reporting endpoint or integrate with a third-party monitoring service. ## CSP constants[¶](#csp-constants "Link to this heading") Django provides predefined constants representing common CSP source expression keywords such as `'self'`, `'none'`, and `'unsafe-inline'`. These constants are intended for use in the directive values defined in the settings. They are available through the [`CSP`](#django.utils.csp.CSP "django.utils.csp.CSP") enum, and using them is recommended over raw strings. This helps avoid common mistakes such as typos, improper quoting, or inconsistent formatting, and ensures compliance with the CSP specification. * *class *CSP[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/utils/csp.py#L11)[¶](#django.utils.csp.CSP "Link to this definition") Enum providing standardized constants for common CSP source expressions. * NONE[¶](#django.utils.csp.CSP.NONE "Link to this definition") Represents `'none'`. Blocks loading resources for the given directive. - REPORT\_SAMPLE[¶](#django.utils.csp.CSP.REPORT_SAMPLE "Link to this definition") Represents `'report-sample'`. Instructs the browser to include a sample of the violating code in reports. Note that this may expose sensitive data. * SELF[¶](#django.utils.csp.CSP.SELF "Link to this definition") Represents `'self'`. Allows loading resources from the same origin (same scheme, host, and port). - STRICT\_DYNAMIC[¶](#django.utils.csp.CSP.STRICT_DYNAMIC "Link to this definition") Represents `'strict-dynamic'`. Allows execution of scripts loaded by a trusted script (e.g., one with a valid nonce or hash), without needing `'unsafe-inline'`. * UNSAFE\_EVAL[¶](#django.utils.csp.CSP.UNSAFE_EVAL "Link to this definition") Represents `'unsafe-eval'`. Allows use of `eval()` and similar JavaScript functions. Strongly discouraged. - UNSAFE\_HASHES[¶](#django.utils.csp.CSP.UNSAFE_HASHES "Link to this definition") Represents `'unsafe-hashes'`. Allows inline event handlers and some `javascript:` URIs when their content hashes match a policy rule. Requires CSP Level 3+. * UNSAFE\_INLINE[¶](#django.utils.csp.CSP.UNSAFE_INLINE "Link to this definition") Represents `'unsafe-inline'`. Allows execution of inline scripts, styles, and `javascript:` URLs. Generally discouraged, especially for scripts. - WASM\_UNSAFE\_EVAL[¶](#django.utils.csp.CSP.WASM_UNSAFE_EVAL "Link to this definition") Represents `'wasm-unsafe-eval'`. Permits compilation and execution of WebAssembly code without enabling `'unsafe-eval'` for scripts. * NONCE[¶](#django.utils.csp.CSP.NONCE "Link to this definition") Django-specific placeholder value (`""`) used in `script-src` or `style-src` directives to activate nonce-based CSP. This string is replaced at runtime by the [`ContentSecurityPolicyMiddleware`](../middleware/#django.middleware.csp.ContentSecurityPolicyMiddleware "django.middleware.csp.ContentSecurityPolicyMiddleware") with a secure, random nonce that is generated for each request. See detailed explanation in [Nonce usage](#csp-nonce). ## Decorators[¶](#module-django.views.decorators.csp "Link to this heading") Django provides decorators to control the Content Security Policy headers on a per-view basis. These allow overriding or disabling the enforced or report-only policy for specific views, providing fine-grained control when the global settings are not sufficient. Applying these overrides fully replaces the base CSP: they do not merge with existing rules. They can be used alongside the constants defined in [`CSP`](#django.utils.csp.CSP "django.utils.csp.CSP"). Warning Weakening or disabling a CSP policy on any page can compromise the security of the entire site. Because of the “same origin” policy, an attacker could exploit a vulnerability on one page to access other parts of the site. * csp\_override(*config)(view*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/decorators/csp.py#L31)[¶](#django.views.decorators.csp.csp_override "Link to this definition") Overrides the `Content-Security-Policy` header for the decorated view using directives in the same format as the [`SECURE_CSP`](../settings/#std-setting-SECURE_CSP) setting. The `config` argument must be a mapping with the desired CSP directives. If `config` is an empty mapping (`{}`), no CSP enforcement header will be added to the response returned by that view, effectively disabling CSP for that view. Examples: ``` from django.http import HttpResponse from django.utils.csp import CSP from django.views.decorators.csp import csp_override @csp_override( { "default-src": [CSP.SELF], "img-src": [CSP.SELF, "data:"], } ) def my_view(request): return HttpResponse("Custom Content-Security-Policy header applied") @csp_override({}) def my_other_view(request): return HttpResponse("No Content-Security-Policy header added") ``` - csp\_report\_only\_override(*config)(view*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/views/decorators/csp.py#L36)[¶](#django.views.decorators.csp.csp_report_only_override "Link to this definition") Overrides the `Content-Security-Policy-Report-Only` header for the decorated view using directives in the same format as the [`SECURE_CSP_REPORT_ONLY`](../settings/#std-setting-SECURE_CSP_REPORT_ONLY) setting. Like [`csp_override()`](#django.views.decorators.csp.csp_override "django.views.decorators.csp.csp_override"), the `config` argument must be a mapping with the desired CSP directives. If `config` is an empty mapping (`{}`), no CSP report-only header will be added to the response returned by that view, effectively disabling report-only CSP for that view. Examples: ``` from django.http import HttpResponse from django.utils.csp import CSP from django.views.decorators.csp import csp_report_only_override @csp_report_only_override( { "default-src": [CSP.SELF], "img-src": [CSP.SELF, "data:"], "report-uri": "https://mysite.com/csp-report/", } ) def my_view(request): return HttpResponse("Custom Content-Security-Policy-Report-Only header applied") @csp_report_only_override({}) def my_other_view(request): return HttpResponse("No Content-Security-Policy-Report-Only header added") ``` The examples above assume function-based views. For class-based views, see the [guide for decorating class-based views](../../topics/class-based-views/intro/#id1). ## Nonce usage[¶](#nonce-usage "Link to this heading") A CSP nonce (“number used once”) is a unique, random value generated per HTTP response. Django supports nonces as a secure way to allow specific inline ` ``` For external ` ``` To render a [`Media`](../../topics/forms/media/#django.forms.Media "django.forms.Media") object’s assets with the nonce applied, pass the object to the [`csp_nonce_attr`](../templates/builtins/#std-templatetag-csp_nonce_attr) template tag: ``` {% csp_nonce_attr form.media %} ``` The browser will only execute inline elements that include a `nonce=` attribute matching the one specified in the `Content-Security-Policy` (or `Content-Security-Policy-Report-Only`) header. This mechanism provides fine-grained control over which inline code is allowed to run. If a template includes the CSP nonce but the policy does not include [`NONCE`](#django.utils.csp.CSP.NONCE "django.utils.csp.CSP.NONCE"), the HTML will include a nonce attribute, but the header will lack the required source expression. In this case, the browser will block the inline script or style (or report it for report-only configurations). ### Nonce generation and caching[¶](#nonce-generation-and-caching "Link to this heading") Django’s nonce generation is **lazy**: the middleware only generates a nonce if `{{ csp_nonce }}` is accessed during template rendering. This avoids unnecessary work for pages that do not use nonces. However, because nonces must be unique per request, extra care is needed when using full-page caching (e.g., Django’s cache middleware, CDN caching). Serving cached responses with previously generated nonces may result in reuse across users and requests. Although such responses may still appear to work (since the nonce in the CSP header and HTML content match), reuse defeats the purpose of the nonce and weakens security. To ensure nonce-based policies remain effective: * Avoid caching full responses that include `{{ csp_nonce }}` or [`csp_nonce_attr`](../templates/builtins/#std-templatetag-csp_nonce_attr). * If caching is necessary, use a strategy that injects a fresh nonce on each request, or consider refactoring your application to avoid inline scripts and styles altogether. [**Back to Top](#top) ## Additional Information ### Support Django! * [Red Robot Studios Ltd donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Content Security Policy](#) * [Overview](#overview) * [Settings](#settings) * [Policy violation reports](#policy-violation-reports) * [CSP constants](#csp-constants) * [Decorators](#module-django.views.decorators.csp) * [Nonce usage](#nonce-usage) * [Nonce generation and caching](#nonce-generation-and-caching) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.10.7/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.10.7/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.10.7/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.10.7/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.10.7/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.10.7/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.10.7/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.10.7/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.10.7/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.10.7/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.10.7/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.10.7/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.10.7/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.10.7/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.10.7/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.10.7/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.10.7/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.10.7/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.10.7/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.10.7/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.10.7/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.10.7/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.10.7/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.10.7/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.10.7/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.10.7/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.10.7/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.10.7/) - [**](#top) # Django 1.10.7 release notes[¶](#django-1-10-7-release-notes "Link to this heading") *April 4, 2017* Django 1.10.7 fixes two security issues and a bug in 1.10.6. * Made admin’s `RelatedFieldWidgetWrapper` use the wrapped widget’s `value_omitted_from_data()` method ([#27905](https://code.djangoproject.com/ticket/27905)). * Fixed model form `default` fallback for `SelectMultiple` ([#27993](https://code.djangoproject.com/ticket/27993)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Benjamin Balder Bach donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.10.7 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.9.4/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.9.4/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.9.4/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.9.4/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.9.4/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.9.4/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.9.4/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.9.4/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.9.4/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.9.4/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.9.4/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.9.4/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.9.4/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.9.4/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.9.4/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.9.4/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.9.4/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.9.4/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.9.4/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.9.4/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.9.4/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.9.4/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.9.4/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.9.4/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.9.4/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.9.4/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.9.4/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.9.4/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.9.4/) - [**](#top) # Django 1.9.4 release notes[¶](#django-1-9-4-release-notes "Link to this heading") *March 5, 2016* Django 1.9.4 fixes a regression on Python 2 in the 1.9.3 security release where `utils.http.is_safe_url()` crashes on bytestring URLs ([#26308](https://code.djangoproject.com/ticket/26308)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Gedankenspieler GbR donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.9.4 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/3.2.7/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/3.2.7/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/3.2.7/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/3.2.7/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/3.2.7/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/3.2.7/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/3.2.7/) - [it](https://docs.djangoproject.com/it/6.1/releases/3.2.7/) - [id](https://docs.djangoproject.com/id/6.1/releases/3.2.7/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/3.2.7/) - [es](https://docs.djangoproject.com/es/6.1/releases/3.2.7/) - [el](https://docs.djangoproject.com/el/6.1/releases/3.2.7/) * * [dev](https://docs.djangoproject.com/en/dev/releases/3.2.7/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/3.2.7/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/3.2.7/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/3.2.7/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/3.2.7/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/3.2.7/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/3.2.7/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/3.2.7/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/3.2.7/) - [**](#top) # Django 3.2.7 release notes[¶](#django-3-2-7-release-notes "Link to this heading") *September 1, 2021* Django 3.2.7 fixes a bug in 3.2.6. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a regression in Django 3.2 that caused the incorrect offset extraction from fixed offset timezones ([#32992](https://code.djangoproject.com/ticket/32992)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Horst Gutmann donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 3.2.7 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/4.2.6/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/4.2.6/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/4.2.6/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/4.2.6/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/4.2.6/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/4.2.6/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/4.2.6/) - [it](https://docs.djangoproject.com/it/6.1/releases/4.2.6/) - [id](https://docs.djangoproject.com/id/6.1/releases/4.2.6/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/4.2.6/) - [es](https://docs.djangoproject.com/es/6.1/releases/4.2.6/) - [el](https://docs.djangoproject.com/el/6.1/releases/4.2.6/) * * [dev](https://docs.djangoproject.com/en/dev/releases/4.2.6/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/4.2.6/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/4.2.6/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/4.2.6/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/4.2.6/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/4.2.6/) - [**](#top) # Django 4.2.6 release notes[¶](#django-4-2-6-release-notes "Link to this heading") *October 4, 2023* Django 4.2.6 fixes a security issue with severity “moderate” and several bugs in 4.2.5. ## CVE-2023-43665: Denial-of-service possibility in `django.utils.text.Truncator`[¶](#cve-2023-43665-denial-of-service-possibility-in-django-utils-text-truncator "Link to this heading") Following the fix for [**CVE 2019-14232**](https://www.cve.org/CVERecord?id=CVE-2019-14232), the regular expressions used in the implementation of `django.utils.text.Truncator`’s `chars()` and `words()` methods (with `html=True`) were revised and improved. However, these regular expressions still exhibited linear backtracking complexity, so when given a very long, potentially malformed HTML input, the evaluation would still be slow, leading to a potential denial of service vulnerability. The `chars()` and `words()` methods are used to implement the [`truncatechars_html`](../../ref/templates/builtins/#std-templatefilter-truncatechars_html) and [`truncatewords_html`](../../ref/templates/builtins/#std-templatefilter-truncatewords_html) template filters, which were thus also vulnerable. The input processed by `Truncator`, when operating in HTML mode, has been limited to the first five million characters in order to avoid potential performance and memory issues. ## Bugfixes[¶](#bugfixes "Link to this heading") * Fixed a regression in Django 4.2.5 where overriding the deprecated `DEFAULT_FILE_STORAGE` and `STATICFILES_STORAGE` settings in tests caused the main `STORAGES` to mutate ([#34821](https://code.djangoproject.com/ticket/34821)). * Fixed a regression in Django 4.2 that caused unnecessary casting of string based fields (`CharField`, `EmailField`, `TextField`, `CICharField`, `CIEmailField`, and `CITextField`) used with the `__isnull` lookup on PostgreSQL. As a consequence, indexes using an `__isnull` expression or condition created before Django 4.2 wouldn’t be used by the query planner, leading to a performance regression ([#34840](https://code.djangoproject.com/ticket/34840)). You may need to recreate such indexes created in your database with Django 4.2 to 4.2.5, as they contain unnecessary `::text` casting. Find candidate indexes with this query: ``` SELECT indexname, indexdef FROM pg_indexes WHERE indexdef LIKE '%::text IS %NULL'; ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [Aniruddha Adhikary donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 4.2.6 release notes](#) * [CVE-2023-43665: Denial-of-service possibility in `django.utils.text.Truncator`](#cve-2023-43665-denial-of-service-possibility-in-django-utils-text-truncator) ---- url: https://docs.djangoproject.com/en/6.1/releases/6.0.9/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/6.0.9/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/6.0.9/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/6.0.9/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/6.0.9/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/6.0.9/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/6.0.9/) - [it](https://docs.djangoproject.com/it/6.1/releases/6.0.9/) - [id](https://docs.djangoproject.com/id/6.1/releases/6.0.9/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/6.0.9/) - [es](https://docs.djangoproject.com/es/6.1/releases/6.0.9/) - [el](https://docs.djangoproject.com/el/6.1/releases/6.0.9/) * * [dev](https://docs.djangoproject.com/en/dev/releases/6.0.9/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/6.0.9/) - [**](#top) # Django 6.0.9 release notes[¶](#django-6-0-9-release-notes "Link to this heading") *October 6, 2026* Django 6.0.9 fixes one security issue with severity “low”, three security issues with severity “moderate”, and provides a fix for an insufficient security mitigation in 6.0.8. It also fixes one data loss issue in 4.0. * Fixed a class of bugs in Django 6.0.8 that allowed bypassing the depth limiter for deeply nested geometry collections ([**CVE 2026-15830**](https://www.cve.org/CVERecord?id=CVE-2026-15830)). The new algorithm treats WKB and WKT inputs more consistently and also fixes a rare case where a valid geometry could have been rejected. * Fixed a data loss issue in Django 4.0 where [network rasters](../../ref/contrib/gis/gdal/#gdal-raster-network) were deleted by GeoDjango when closed. [**Back to Top](#top) ## Additional Information ### Support Django! * [Mikuláš Poul donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 6.0.9 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/ref/models/meta/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/models/meta/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/models/meta/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/models/meta/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/models/meta/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/models/meta/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/models/meta/) - [it](https://docs.djangoproject.com/it/6.1/ref/models/meta/) - [id](https://docs.djangoproject.com/id/6.1/ref/models/meta/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/models/meta/) - [es](https://docs.djangoproject.com/es/6.1/ref/models/meta/) - [el](https://docs.djangoproject.com/el/6.1/ref/models/meta/) * * [dev](https://docs.djangoproject.com/en/dev/ref/models/meta/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/models/meta/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/models/meta/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/models/meta/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/models/meta/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/models/meta/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/models/meta/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/models/meta/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/models/meta/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/models/meta/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/models/meta/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/models/meta/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/models/meta/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/models/meta/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/models/meta/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/models/meta/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/models/meta/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/models/meta/) - [**](#top) # Model `_meta` API[¶](#module-django.db.models.options "Link to this heading") * *class *Options[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/db/models/options.py#L90)[¶](#django.db.models.options.Options "Link to this definition") The model `_meta` API is at the core of the Django ORM. It enables other parts of the system such as lookups, queries, forms, and the admin to understand the capabilities of each model. The API is accessible through the `_meta` attribute of each model class, which is an instance of an `django.db.models.options.Options` object. Methods and attributes that it provides can be used to: * Retrieve all field instances of a model * Retrieve a single field instance of a model by name * Retrieve all fields that compose the primary key of a model ## Field access API[¶](#field-access-api "Link to this heading") ### Retrieving a single field instance of a model by name[¶](#retrieving-a-single-field-instance-of-a-model-by-name "Link to this heading") * Options.get\_field(*field\_name*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/db/models/options.py#L670)[¶](#django.db.models.options.Options.get_field "Link to this definition") Returns the field instance given a name of a field. `field_name` can be the name of a field on the model, a field on an abstract or inherited model, or a field defined on another model that points to the model. In the latter case, the `field_name` will be (in order of preference) the [`related_query_name`](../fields/#django.db.models.ForeignKey.related_query_name "django.db.models.ForeignKey.related_query_name") set by the user, the [`related_name`](../fields/#django.db.models.ForeignKey.related_name "django.db.models.ForeignKey.related_name") set by the user, or the name automatically generated by Django. Hidden fields, fields with [`hidden=True`](../fields/#django.db.models.Field.hidden "django.db.models.Field.hidden"), cannot be retrieved by name. If a field with the given name is not found a [`FieldDoesNotExist`](../../exceptions/#django.core.exceptions.FieldDoesNotExist "django.core.exceptions.FieldDoesNotExist") exception will be raised. ``` >>> from django.contrib.auth.models import User # A field on the model >>> User._meta.get_field("username") # A field from another model that has a relation with the current model >>> User._meta.get_field("logentry") # A non existent field >>> User._meta.get_field("does_not_exist") Traceback (most recent call last): ... FieldDoesNotExist: User has no field named 'does_not_exist' ``` ### Retrieving all field instances of a model[¶](#retrieving-all-field-instances-of-a-model "Link to this heading") * Options.get\_fields(*include\_parents=True*, *include\_hidden=False*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/db/models/options.py#L865)[¶](#django.db.models.options.Options.get_fields "Link to this definition") Returns a tuple of fields associated with a model. `get_fields()` accepts two parameters that can be used to control which fields are returned: * `include_parents` `True` by default. Recursively includes fields defined on parent classes. If set to `False`, `get_fields()` will only search for fields declared directly on the current model. Fields from models that directly inherit from abstract models or proxy classes are considered to be local, not on the parent. * `include_hidden` `False` by default. If set to `True`, `get_fields()` will include fields with [`hidden=True`](../fields/#django.db.models.Field.hidden "django.db.models.Field.hidden"). ``` >>> from django.contrib.auth.models import User >>> User._meta.get_fields() (, , , , , , , , , , , , , ) # Also include hidden fields. >>> User._meta.get_fields(include_hidden=True) (, , , , , , , , , , , , , , , ) ``` ### Retrieving fields composing the primary key of a model[¶](#retrieving-fields-composing-the-primary-key-of-a-model "Link to this heading") * Options.pk\_fields[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/db/models/options.py#L993)[¶](#django.db.models.options.Options.pk_fields "Link to this definition") Returns a list of the fields composing the primary key of a model. When a [`CompositePrimaryKey`](../fields/#django.db.models.CompositePrimaryKey "django.db.models.CompositePrimaryKey") is defined on a model it will contain all the fields referenced by it. ``` from django.db import models class TenantUser(models.Model): pk = models.CompositePrimaryKey("tenant_id", "id") tenant_id = models.IntegerField() id = models.IntegerField() ``` ``` >>> TenantUser._meta.pk_fields [ , ] ``` Otherwise it will contain the single field declared as the primary key of the model, either explicitly with [`primary_key=True`](../fields/#django.db.models.Field.primary_key "django.db.models.Field.primary_key") or implicitly as the [automatic primary key](../../../topics/db/models/#automatic-primary-key-fields). ``` >>> User._meta.pk_fields [] ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [Car CB Radios donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Model `_meta` API](#) * [Field access API](#field-access-api) * [Retrieving a single field instance of a model by name](#retrieving-a-single-field-instance-of-a-model-by-name) * [Retrieving all field instances of a model](#retrieving-all-field-instances-of-a-model) * [Retrieving fields composing the primary key of a model](#retrieving-fields-composing-the-primary-key-of-a-model) ---- url: https://docs.djangoproject.com/en/6.1/topics/templates/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/templates/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/templates/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/templates/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/templates/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/templates/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/templates/) - [it](https://docs.djangoproject.com/it/6.1/topics/templates/) - [id](https://docs.djangoproject.com/id/6.1/topics/templates/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/templates/) - [es](https://docs.djangoproject.com/es/6.1/topics/templates/) - [el](https://docs.djangoproject.com/el/6.1/topics/templates/) * * [dev](https://docs.djangoproject.com/en/dev/topics/templates/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/templates/) * [5.2](https://docs.djangoproject.com/en/5.2/topics/templates/) * [5.1](https://docs.djangoproject.com/en/5.1/topics/templates/) * [5.0](https://docs.djangoproject.com/en/5.0/topics/templates/) * [4.2](https://docs.djangoproject.com/en/4.2/topics/templates/) * [4.1](https://docs.djangoproject.com/en/4.1/topics/templates/) * [4.0](https://docs.djangoproject.com/en/4.0/topics/templates/) * [3.2](https://docs.djangoproject.com/en/3.2/topics/templates/) * [3.1](https://docs.djangoproject.com/en/3.1/topics/templates/) * [3.0](https://docs.djangoproject.com/en/3.0/topics/templates/) * [2.2](https://docs.djangoproject.com/en/2.2/topics/templates/) * [2.1](https://docs.djangoproject.com/en/2.1/topics/templates/) * [2.0](https://docs.djangoproject.com/en/2.0/topics/templates/) * [1.11](https://docs.djangoproject.com/en/1.11/topics/templates/) * [1.10](https://docs.djangoproject.com/en/1.10/topics/templates/) * [1.9](https://docs.djangoproject.com/en/1.9/topics/templates/) * [1.8](https://docs.djangoproject.com/en/1.8/topics/templates/) - [**](#top) # Templates[¶](#module-django.template "Link to this heading") Being a web framework, Django needs a convenient way to generate HTML dynamically. The most common approach relies on templates. A template contains the static parts of the desired HTML output as well as some special syntax describing how dynamic content will be inserted. For a hands-on example of creating HTML pages with templates, see [Tutorial 3](../../intro/tutorial03/). A Django project can be configured with one or several template engines (or even zero if you don’t use templates). Django ships built-in backends for its own template system, creatively called the Django template language (DTL), and for the popular alternative [Jinja2](https://jinja.palletsprojects.com/). Backends for other template languages may be available from third-parties. You can also write your own custom backend, see [Custom template backend](../../howto/custom-template-backend/) Django defines a standard API for loading and rendering templates regardless of the backend. Loading consists of finding the template for a given identifier and preprocessing it, usually compiling it to an in-memory representation. Rendering means interpolating the template with context data and returning the resulting string. The [Django template language](../../ref/templates/language/) is Django’s own template system. Until Django 1.8 it was the only built-in option available. It’s a good template library even though it’s fairly opinionated and sports a few idiosyncrasies. If you don’t have a pressing reason to choose another backend, you should use the DTL, especially if you’re writing a pluggable application and you intend to distribute templates. Django’s contrib apps that include templates, like [django.contrib.admin](../../ref/contrib/admin/), use the DTL. For historical reasons, both the generic support for template engines and the implementation of the Django template language live in the `django.template` namespace. Warning The template system isn’t safe against untrusted template authors. For example, a site shouldn’t allow its users to provide their own templates, since template authors can do things like perform XSS attacks and access properties of template variables that may contain sensitive information. ## The Django template language[¶](#the-django-template-language "Link to this heading") ### Syntax[¶](#syntax "Link to this heading") About this section This is an overview of the Django template language’s syntax. For details see the [language syntax reference](../../ref/templates/language/). A Django template is a text document or a Python string marked-up using the Django template language. Some constructs are recognized and interpreted by the template engine. The main ones are variables and tags. A template is rendered with a context. Rendering replaces variables with their values, which are looked up in the context, and executes tags. Everything else is output as is. The syntax of the Django template language involves four constructs. #### Variables[¶](#variables "Link to this heading") A variable outputs a value from the context, which is a dict-like object mapping keys to values. Variables are surrounded by `{{` and `}}` like this: ``` My first name is {{ first_name }}. My last name is {{ last_name }}. ``` With a context of `{'first_name': 'John', 'last_name': 'Doe'}`, this template renders to: ``` My first name is John. My last name is Doe. ``` Dictionary lookup, attribute lookup and list-index lookups are implemented with a dot notation: ``` {{ my_dict.key }} {{ my_object.attribute }} {{ my_list.0 }} ``` If a variable resolves to a callable, the template system will call it with no arguments and use its result instead of the callable. #### Tags[¶](#tags "Link to this heading") Tags provide arbitrary logic in the rendering process. This definition is deliberately vague. For example, a tag can output content, serve as a control structure e.g. an “if” statement or a “for” loop, grab content from a database, or even enable access to other template tags. Tags are surrounded by `{%` and `%}` like this: ``` {% csrf_token %} ``` Most tags accept arguments: ``` {% cycle 'odd' 'even' %} ``` Some tags require beginning and ending tags: ``` {% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %} ``` A [reference of built-in tags](../../ref/templates/builtins/#ref-templates-builtins-tags) is available as well as [instructions for writing custom tags](../../howto/custom-template-tags/#howto-writing-custom-template-tags). #### Filters[¶](#filters "Link to this heading") Filters transform the values of variables and tag arguments. They look like this: ``` {{ django|title }} ``` With a context of `{'django': 'the web framework for perfectionists with deadlines'}`, this template renders to: ``` The Web Framework For Perfectionists With Deadlines ``` Some filters take an argument: ``` {{ my_date|date:"Y-m-d" }} ``` A [reference of built-in filters](../../ref/templates/builtins/#ref-templates-builtins-filters) is available as well as [instructions for writing custom filters](../../howto/custom-template-tags/#howto-writing-custom-template-filters). #### Comments[¶](#comments "Link to this heading") Comments look like this: ``` {# this won't be rendered #} ``` A [`{% comment %}`](../../ref/templates/builtins/#std-templatetag-comment) tag provides multi-line comments. ### Components[¶](#components "Link to this heading") About this section This is an overview of the Django template language’s APIs. For details see the [API reference](../../ref/templates/api/). #### Engine[¶](#engine "Link to this heading") [`django.template.Engine`](../../ref/templates/api/#django.template.Engine "django.template.Engine") encapsulates an instance of the Django template system. The main reason for instantiating an [`Engine`](../../ref/templates/api/#django.template.Engine "django.template.Engine") directly is to use the Django template language outside of a Django project. [`django.template.backends.django.DjangoTemplates`](#django.template.backends.django.DjangoTemplates "django.template.backends.django.DjangoTemplates") is a thin wrapper adapting [`django.template.Engine`](../../ref/templates/api/#django.template.Engine "django.template.Engine") to Django’s template backend API. #### Template[¶](#template "Link to this heading") [`django.template.Template`](../../ref/templates/api/#django.template.Template "django.template.Template") represents a compiled template. Templates are obtained with [`Engine.get_template()`](../../ref/templates/api/#django.template.Engine.get_template "django.template.Engine.get_template") or [`Engine.from_string()`](../../ref/templates/api/#django.template.Engine.from_string "django.template.Engine.from_string"). Likewise `django.template.backends.django.Template` is a thin wrapper adapting [`django.template.Template`](../../ref/templates/api/#django.template.Template "django.template.Template") to the common template API. #### Context[¶](#context "Link to this heading") [`django.template.Context`](../../ref/templates/api/#django.template.Context "django.template.Context") holds some metadata in addition to the context data. It is passed to [`Template.render()`](../../ref/templates/api/#django.template.Template.render "django.template.Template.render") for rendering a template. [`django.template.RequestContext`](../../ref/templates/api/#django.template.RequestContext "django.template.RequestContext") is a subclass of [`Context`](../../ref/templates/api/#django.template.Context "django.template.Context") that stores the current [`HttpRequest`](../../ref/request-response/#django.http.HttpRequest "django.http.HttpRequest") and runs template context processors. The common API doesn’t have an equivalent concept. Context data is passed in a plain [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") and the current [`HttpRequest`](../../ref/request-response/#django.http.HttpRequest "django.http.HttpRequest") is passed separately if needed. #### Loaders[¶](#loaders "Link to this heading") Template loaders are responsible for locating templates, loading them, and returning [`Template`](../../ref/templates/api/#django.template.Template "django.template.Template") objects. Django provides several [built-in template loaders](../../ref/templates/api/#template-loaders) and supports [custom template loaders](../../ref/templates/api/#custom-template-loaders). #### Context processors[¶](#context-processors "Link to this heading") Context processors are functions that receive the current [`HttpRequest`](../../ref/request-response/#django.http.HttpRequest "django.http.HttpRequest") as an argument and return a [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") of data to be added to the rendering context. Their main use is to add common data shared by all templates to the context without repeating code in every view. Django provides many [built-in context processors](../../ref/templates/api/#context-processors), and you can implement your own additional context processors, too. ## Support for template engines[¶](#support-for-template-engines "Link to this heading") ### Configuration[¶](#configuration "Link to this heading") Templates engines are configured with the [`TEMPLATES`](../../ref/settings/#std-setting-TEMPLATES) setting. It’s a list of configurations, one for each engine. The default value is empty. The `settings.py` generated by the [`startproject`](../../ref/django-admin/#django-admin-startproject) command defines a more useful value: ``` TEMPLATES = [ { "BACKEND": "django.template.backends.django.DjangoTemplates", "DIRS": [], "APP_DIRS": True, "OPTIONS": { # ... some options here ... }, }, ] ``` [`BACKEND`](../../ref/settings/#std-setting-TEMPLATES-BACKEND) is a dotted Python path to a template engine class implementing Django’s template backend API. The built-in backends are [`django.template.backends.django.DjangoTemplates`](#django.template.backends.django.DjangoTemplates "django.template.backends.django.DjangoTemplates") and [`django.template.backends.jinja2.Jinja2`](#django.template.backends.jinja2.Jinja2 "django.template.backends.jinja2.Jinja2"). Since most engines load templates from files, the top-level configuration for each engine contains two common settings: * [`DIRS`](../../ref/settings/#std-setting-TEMPLATES-DIRS) defines a list of directories where the engine should look for template source files, in search order. * [`APP_DIRS`](../../ref/settings/#std-setting-TEMPLATES-APP_DIRS) tells whether the engine should look for templates inside installed applications. Each backend defines a conventional name for the subdirectory inside applications where its templates should be stored. While uncommon, it’s possible to configure several instances of the same backend with different options. In that case you should define a unique [`NAME`](../../ref/settings/#std-setting-TEMPLATES-NAME) for each engine. [`OPTIONS`](../../ref/settings/#std-setting-TEMPLATES-OPTIONS) contains backend-specific settings. ### Usage[¶](#module-django.template.loader "Link to this heading") The `django.template.loader` module defines two functions to load templates. * get\_template(*template\_name*, *using=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/loader.py#L5)[¶](#django.template.loader.get_template "Link to this definition") This function loads the template with the given name and returns a `Template` object. The exact type of the return value depends on the backend that loaded the template. Each backend has its own `Template` class. `get_template()` tries each template engine in order until one succeeds. If the template cannot be found, it raises [`TemplateDoesNotExist`](#django.template.TemplateDoesNotExist "django.template.TemplateDoesNotExist"). If the template is found but contains invalid syntax, it raises [`TemplateSyntaxError`](#django.template.TemplateSyntaxError "django.template.TemplateSyntaxError"). How templates are searched and loaded depends on each engine’s backend and configuration. If you want to restrict the search to a particular template engine, pass the engine’s [`NAME`](../../ref/settings/#std-setting-TEMPLATES-NAME) in the `using` argument. **Partial loading:** When using the [`DjangoTemplates`](#django.template.backends.django.DjangoTemplates "django.template.backends.django.DjangoTemplates") backend, a specific fragment from a template can be loaded by name. This fragment should have been previously defined using the [`partialdef`](../../ref/templates/builtins/#std-templatetag-partialdef) template tag: ``` from django.template.loader import get_template # Load an entire template. template = get_template("template.html") # Load a specific fragment from a template. partial = get_template("template.html#partial_name") ``` When loading a partial, the returned object behaves like a regular `Template` but contains only the partial’s content. See [Template partials](../../ref/templates/language/#template-partials) for more information about defining and using template fragments. Changed in Django 6.0: Support for loading template partials when using the [`DjangoTemplates`](#django.template.backends.django.DjangoTemplates "django.template.backends.django.DjangoTemplates") backend was added. - select\_template(*template\_name\_list*, *using=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/loader.py#L22)[¶](#django.template.loader.select_template "Link to this definition") `select_template()` is just like `get_template()`, except it takes a list of template names. It tries each name in order and returns the first template that exists. If loading a template fails, the following two exceptions, defined in `django.template`, may be raised: * *exception *TemplateDoesNotExist(*msg*, *tried=None*, *backend=None*, *chain=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/exceptions.py#L9)[¶](#django.template.TemplateDoesNotExist "Link to this definition") This exception is raised when a template cannot be found. It accepts the following optional arguments for populating the [template postmortem](../../howto/custom-template-backend/#template-postmortem) on the debug page: * `backend` The template backend instance from which the exception originated. * `tried` A list of sources that were tried when finding the template. This is formatted as a list of tuples containing `(origin, status)`, where `origin` is an [origin-like](../../howto/custom-template-backend/#template-origin-api) object and `status` is a string with the reason the template wasn’t found. * `chain` A list of intermediate [`TemplateDoesNotExist`](#django.template.TemplateDoesNotExist "django.template.TemplateDoesNotExist") exceptions raised when trying to load a template. This is used by functions, such as [`get_template()`](#django.template.loader.get_template "django.template.loader.get_template"), that try to load a given template from multiple engines. - *exception *TemplateSyntaxError(*msg*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/exceptions.py#L39)[¶](#django.template.TemplateSyntaxError "Link to this definition") This exception is raised when a template was found but contains errors. `Template` objects returned by `get_template()` and `select_template()` must provide a `render()` method with the following signature: * Template.render(*context=None*, *request=None*)[¶](#django.template.backends.base.Template.render "Link to this definition") Renders this template with a given context. If `context` is provided, it must be a [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)"). If it isn’t provided, the engine will render the template with an empty context. If `request` is provided, it must be an [`HttpRequest`](../../ref/request-response/#django.http.HttpRequest "django.http.HttpRequest"). Then the engine must make it, as well as the CSRF token, available in the template. How this is achieved is up to each backend. Here’s an example of the search algorithm. For this example the [`TEMPLATES`](../../ref/settings/#std-setting-TEMPLATES) setting is: ``` TEMPLATES = [ { "BACKEND": "django.template.backends.django.DjangoTemplates", "DIRS": [ "/home/html/example.com", "/home/html/default", ], }, { "BACKEND": "django.template.backends.jinja2.Jinja2", "DIRS": [ "/home/html/jinja2", ], }, ] ``` If you call `get_template('story_detail.html')`, here are the files Django will look for, in order: * `/home/html/example.com/story_detail.html` (`'django'` engine) * `/home/html/default/story_detail.html` (`'django'` engine) * `/home/html/jinja2/story_detail.html` (`'jinja2'` engine) If you call `select_template(['story_253_detail.html', 'story_detail.html'])`, here’s what Django will look for: * `/home/html/example.com/story_253_detail.html` (`'django'` engine) * `/home/html/default/story_253_detail.html` (`'django'` engine) * `/home/html/jinja2/story_253_detail.html` (`'jinja2'` engine) * `/home/html/example.com/story_detail.html` (`'django'` engine) * `/home/html/default/story_detail.html` (`'django'` engine) * `/home/html/jinja2/story_detail.html` (`'jinja2'` engine) When Django finds a template that exists, it stops looking. Use `django.template.loader.select_template()` for more flexibility You can use [`select_template()`](#django.template.loader.select_template "django.template.loader.select_template") for flexible template loading. For example, if you’ve written a news story and want some stories to have custom templates, use something like `select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])`. That’ll allow you to use a custom template for an individual story, with a fallback template for stories that don’t have custom templates. It’s possible – and preferable – to organize templates in subdirectories inside each directory containing templates. The convention is to make a subdirectory for each Django app, with subdirectories within those subdirectories as needed. Do this for your own sanity. Storing all templates in the root level of a single directory gets messy. To load a template that’s within a subdirectory, use a slash, like so: ``` get_template("news/story_detail.html") ``` Using the same [`TEMPLATES`](../../ref/settings/#std-setting-TEMPLATES) option as above, this will attempt to load the following templates: * `/home/html/example.com/news/story_detail.html` (`'django'` engine) * `/home/html/default/news/story_detail.html` (`'django'` engine) * `/home/html/jinja2/news/story_detail.html` (`'jinja2'` engine) In addition, to cut down on the repetitive nature of loading and rendering templates, Django provides a shortcut function which automates the process. * render\_to\_string(*template\_name*, *context=None*, *request=None*, *using=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/loader.py#L52)[¶](#django.template.loader.render_to_string "Link to this definition") `render_to_string()` loads a template like [`get_template()`](#django.template.loader.get_template "django.template.loader.get_template") and calls its `render()` method immediately. It takes the following arguments. * `template_name` The name of the template to load and render. If it’s a list of template names, Django uses [`select_template()`](#django.template.loader.select_template "django.template.loader.select_template") instead of [`get_template()`](#django.template.loader.get_template "django.template.loader.get_template") to find the template. * `context` A [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") to be used as the template’s context for rendering. * `request` An optional [`HttpRequest`](../../ref/request-response/#django.http.HttpRequest "django.http.HttpRequest") that will be available during the template’s rendering process. * `using` An optional template engine [`NAME`](../../ref/settings/#std-setting-TEMPLATES-NAME). The search for the template will be restricted to that engine. Usage example: ``` from django.template.loader import render_to_string rendered = render_to_string("my_template.html", {"foo": "bar"}) ``` See also the [`render()`](../http/shortcuts/#django.shortcuts.render "django.shortcuts.render") shortcut which calls [`render_to_string()`](#django.template.loader.render_to_string "django.template.loader.render_to_string") and feeds the result into an [`HttpResponse`](../../ref/request-response/#django.http.HttpResponse "django.http.HttpResponse") suitable for returning from a view. Finally, you can use configured engines directly: * engines[¶](#django.template.loader.engines "Link to this definition") Template engines are available in `django.template.engines`: ``` from django.template import engines django_engine = engines["django"] template = django_engine.from_string("Hello {{ name }}!") ``` The lookup key — `'django'` in this example — is the engine’s [`NAME`](../../ref/settings/#std-setting-TEMPLATES-NAME). ### Built-in backends[¶](#module-django.template.backends.django "Link to this heading") * *class *DjangoTemplates[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/backends/django.py#L16)[¶](#django.template.backends.django.DjangoTemplates "Link to this definition") Set [`BACKEND`](../../ref/settings/#std-setting-TEMPLATES-BACKEND) to `'django.template.backends.django.DjangoTemplates'` to configure a Django template engine. When [`APP_DIRS`](../../ref/settings/#std-setting-TEMPLATES-APP_DIRS) is `True`, `DjangoTemplates` engines look for templates in the `templates` subdirectory of installed applications. This generic name was kept for backwards-compatibility. `DjangoTemplates` engines accept the following [`OPTIONS`](../../ref/settings/#std-setting-TEMPLATES-OPTIONS): * `'autoescape'`: a boolean that controls whether HTML autoescaping is enabled. It defaults to `True`. Warning Only set it to `False` if you’re rendering non-HTML templates! * `'context_processors'`: a list of dotted Python paths to callables that are used to populate the context when a template is rendered with a request. These callables take a request object as their argument and return a [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") of items to be merged into the context. It defaults to an empty list. See [`RequestContext`](../../ref/templates/api/#django.template.RequestContext "django.template.RequestContext") for more information. * `'debug'`: a boolean that turns on/off template debug mode. If it is `True`, the fancy error page will display a detailed report for any exception raised during template rendering. This report contains the relevant snippet of the template with the appropriate line highlighted. It defaults to the value of the [`DEBUG`](../../ref/settings/#std-setting-DEBUG) setting. * `'loaders'`: a list of dotted Python paths to template loader classes. Each `Loader` class knows how to import templates from a particular source. Optionally, a tuple can be used instead of a string. The first item in the tuple should be the `Loader` class name, and subsequent items are passed to the `Loader` during initialization. The default depends on the values of [`DIRS`](../../ref/settings/#std-setting-TEMPLATES-DIRS) and [`APP_DIRS`](../../ref/settings/#std-setting-TEMPLATES-APP_DIRS). See [Loader types](../../ref/templates/api/#template-loaders) for details. * `'string_if_invalid'`: the output, as a string, that the template system should use for invalid (e.g. misspelled) variables. It defaults to an empty string. See [How invalid variables are handled](../../ref/templates/api/#invalid-template-variables) for details. * `'file_charset'`: the charset used to read template files on disk. It defaults to `'utf-8'`. * `'libraries'`: A dictionary of labels and dotted Python paths of template tag modules to register with the template engine. This can be used to add new libraries or provide alternate labels for existing ones. For example: ``` OPTIONS = { "libraries": { "myapp_tags": "path.to.myapp.tags", "admin.urls": "django.contrib.admin.templatetags.admin_urls", }, } ``` Libraries can be loaded by passing the corresponding dictionary key to the [`{% load %}`](../../ref/templates/builtins/#std-templatetag-load) tag. * `'builtins'`: A list of dotted Python paths of template tag modules to add to [built-ins](../../ref/templates/builtins/). For example: ``` OPTIONS = { "builtins": ["myapp.builtins"], } ``` Tags and filters from built-in libraries can be used without first calling the [`{% load %}`](../../ref/templates/builtins/#std-templatetag-load) tag. - *class *Jinja2[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/template/backends/jinja2.py#L14)[¶](#django.template.backends.jinja2.Jinja2 "Link to this definition") Requires [Jinja2](https://jinja.palletsprojects.com/) to be installed: /  ``` $ python -m pip install Jinja2 ``` ** ``` ...\> py -m pip install Jinja2 ``` ** Set [`BACKEND`](../../ref/settings/#std-setting-TEMPLATES-BACKEND) to `'django.template.backends.jinja2.Jinja2'` to configure a [Jinja2](https://jinja.palletsprojects.com/) engine. When [`APP_DIRS`](../../ref/settings/#std-setting-TEMPLATES-APP_DIRS) is `True`, `Jinja2` engines look for templates in the `jinja2` subdirectory of installed applications. The most important entry in [`OPTIONS`](../../ref/settings/#std-setting-TEMPLATES-OPTIONS) is `'environment'`. It’s a dotted Python path to a callable returning a Jinja2 environment. It defaults to `'jinja2.Environment'`. Django invokes that callable and passes other options as keyword arguments. Furthermore, Django adds defaults that differ from Jinja2’s for a few options: * `'autoescape'`: `True` * `'loader'`: a loader configured for [`DIRS`](../../ref/settings/#std-setting-TEMPLATES-DIRS) and [`APP_DIRS`](../../ref/settings/#std-setting-TEMPLATES-APP_DIRS) * `'auto_reload'`: `settings.DEBUG` * `'undefined'`: `DebugUndefined if settings.DEBUG else Undefined` `Jinja2` engines also accept the following [`OPTIONS`](../../ref/settings/#std-setting-TEMPLATES-OPTIONS): * `'context_processors'`: a list of dotted Python paths to callables that are used to populate the context when a template is rendered with a request. These callables take a request object as their argument and return a [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") of items to be merged into the context. It defaults to an empty list. Using context processors with Jinja2 templates is discouraged. Context processors are useful with Django templates because Django templates don’t support calling functions with arguments. Since Jinja2 doesn’t have that limitation, it’s recommended to put the function that you would use as a context processor in the global variables available to the template using `jinja2.Environment` as described below. You can then call that function in the template: ``` {{ function(request) }} ``` Some Django templates context processors return a fixed value. For Jinja2 templates, this layer of indirection isn’t necessary since you can add constants directly in `jinja2.Environment`. The original use case for adding context processors for Jinja2 involved: * Making an expensive computation that depends on the request. * Needing the result in every template. * Using the result multiple times in each template. Unless all of these conditions are met, passing a function to the template is more in line with the design of Jinja2. The default configuration is purposefully kept to a minimum. If a template is rendered with a request (e.g. when using [`render()`](../http/shortcuts/#django.shortcuts.render "django.shortcuts.render")), the `Jinja2` backend adds the globals `request`, `csrf_input`, and `csrf_token` to the context. Apart from that, this backend doesn’t create a Django-flavored environment. It doesn’t know about Django filters and tags. In order to use Django-specific APIs, you must configure them into the environment. For example, you can create `myproject/jinja2.py` with this content: ``` from django.templatetags.static import static from django.urls import reverse from jinja2 import Environment def environment(**options): env = Environment(**options) env.globals.update( { "static": static, "url": reverse, } ) return env ``` and set the `'environment'` option to `'myproject.jinja2.environment'`. Then you could use the following constructs in Jinja2 templates: ``` Company Logo Administration ``` The concepts of tags and filters exist both in the Django template language and in Jinja2 but they’re used differently. Since Jinja2 supports passing arguments to callables in templates, many features that require a template tag or filter in Django templates can be achieved by calling a function in Jinja2 templates, as shown in the example above. Jinja2’s global namespace removes the need for template context processors. The Django template language doesn’t have an equivalent of Jinja2 tests. [**Back to Top](#top) ## Additional Information ### Support Django! * [Gem Logic donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Templates](#) * [The Django template language](#the-django-template-language) * [Syntax](#syntax) * [Variables](#variables) * [Tags](#tags) * [Filters](#filters) * [Comments](#comments) * [Components](#components) * [Engine](#engine) * [Template](#template) * [Context](#context) * [Loaders](#loaders) * [Context processors](#context-processors) * [Support for template engines](#support-for-template-engines) * [Configuration](#configuration) * [Usage](#module-django.template.loader) * [Built-in backends](#module-django.template.backends.django) ---- url: https://docs.djangoproject.com/en/6.1/howto/windows/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/howto/windows/) - [sv](https://docs.djangoproject.com/sv/6.1/howto/windows/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/howto/windows/) - [pl](https://docs.djangoproject.com/pl/6.1/howto/windows/) - [ko](https://docs.djangoproject.com/ko/6.1/howto/windows/) - [ja](https://docs.djangoproject.com/ja/6.1/howto/windows/) - [it](https://docs.djangoproject.com/it/6.1/howto/windows/) - [id](https://docs.djangoproject.com/id/6.1/howto/windows/) - [fr](https://docs.djangoproject.com/fr/6.1/howto/windows/) - [es](https://docs.djangoproject.com/es/6.1/howto/windows/) - [el](https://docs.djangoproject.com/el/6.1/howto/windows/) * * [dev](https://docs.djangoproject.com/en/dev/howto/windows/) * [6.0](https://docs.djangoproject.com/en/6.0/howto/windows/) * [5.2](https://docs.djangoproject.com/en/5.2/howto/windows/) * [5.1](https://docs.djangoproject.com/en/5.1/howto/windows/) * [5.0](https://docs.djangoproject.com/en/5.0/howto/windows/) * [4.2](https://docs.djangoproject.com/en/4.2/howto/windows/) * [4.1](https://docs.djangoproject.com/en/4.1/howto/windows/) * [4.0](https://docs.djangoproject.com/en/4.0/howto/windows/) * [3.2](https://docs.djangoproject.com/en/3.2/howto/windows/) * [3.1](https://docs.djangoproject.com/en/3.1/howto/windows/) * [3.0](https://docs.djangoproject.com/en/3.0/howto/windows/) * [2.2](https://docs.djangoproject.com/en/2.2/howto/windows/) * [2.1](https://docs.djangoproject.com/en/2.1/howto/windows/) * [2.0](https://docs.djangoproject.com/en/2.0/howto/windows/) * [1.11](https://docs.djangoproject.com/en/1.11/howto/windows/) * [1.10](https://docs.djangoproject.com/en/1.10/howto/windows/) * [1.9](https://docs.djangoproject.com/en/1.9/howto/windows/) * [1.8](https://docs.djangoproject.com/en/1.8/howto/windows/) - [**](#top) # How to install Django on Windows[¶](#how-to-install-django-on-windows "Link to this heading") This document will guide you through installing Python 3.15 and Django on Windows. It also provides instructions for setting up a virtual environment, which makes it easier to work on Python projects. This is meant as a beginner’s guide for users working on Django projects and does not reflect how Django should be installed when developing changes for Django itself. The steps in this guide have been tested with Windows 10. In other versions, the steps would be similar. You will need to be familiar with using the Windows command prompt. ## Install Python[¶](#install-python "Link to this heading") Django is a Python web framework, thus requiring Python to be installed on your machine. At the time of writing, Python 3.15 is the latest version. To install Python on your machine go to . The website should offer you a download button for the latest Python version. Download the executable installer and run it. Check the boxes next to “Install launcher for all users (recommended)” then click “Install Now”. After installation, open the command prompt and check that the Python version matches the version you installed by executing: ``` ...\> py --version ``` `py` is not recognized or found Depending on how you’ve installed Python (such as via the Microsoft Store), `py` may not be available in the command prompt. You will then need to use `python` instead of `py` when entering commands. See also For more details, see [Using Python on Windows](https://docs.python.org/3/using/windows.html "(in Python v3.15)") documentation. ## About `pip`[¶](#about-pip "Link to this heading") [pip](https://pypi.org/project/pip/) is a package manager for Python and is included by default with the Python installer. It helps to install and uninstall Python packages (such as Django!). For the rest of the installation, we’ll use `pip` to install Python packages from the command line. ## Setting up a virtual environment[¶](#setting-up-a-virtual-environment "Link to this heading") It is best practice to provide a dedicated environment for each Django project you create. There are many options to manage environments and packages within the Python ecosystem, some of which are recommended in the [Python documentation](https://packaging.python.org/guides/tool-recommendations/). Python itself comes with [venv](https://docs.python.org/3/tutorial/venv.html "(in Python v3.15)") for managing environments which we will use for this guide. To create a virtual environment for your project, open a new command prompt, navigate to the folder where you want to create your project and then enter the following: ``` ...\> py -m venv project-name ``` This will create a folder called ‘project-name’ if it does not already exist and set up the virtual environment. To activate the environment, run: ``` ...\> project-name\Scripts\activate.bat ``` The virtual environment will be activated and you’ll see “(project-name)” next to the command prompt to designate that. Each time you start a new command prompt, you’ll need to activate the environment again. ## Install Django[¶](#install-django "Link to this heading") Django can be installed easily using `pip` within your virtual environment. In the command prompt, ensure your virtual environment is active, and execute the following command: ``` ...\> py -m pip install Django ``` This will download and install the latest Django release. After the installation has completed, you can verify your Django installation by executing `django-admin --version` in the command prompt. See [Get your database running](../../topics/install/#database-installation) for information on database installation with Django. ## Colored terminal output[¶](#colored-terminal-output "Link to this heading") A quality-of-life feature adds colored (rather than monochrome) output to the terminal. In modern terminals this should work for both CMD and PowerShell. If for some reason this needs to be disabled, set the environmental variable [`DJANGO_COLORS`](../../ref/django-admin/#envvar-DJANGO_COLORS) to `nocolor`. On older Windows versions, or legacy terminals, [colorama](https://pypi.org/project/colorama/) 0.4.6+ must be installed to enable syntax coloring: ``` ...\> py -m pip install "colorama >= 0.4.6" ``` See [Syntax coloring](../../ref/django-admin/#syntax-coloring) for more information on color settings. ## Common pitfalls[¶](#common-pitfalls "Link to this heading") * If `django-admin` only displays the help text no matter what arguments it is given, there is probably a problem with the file association in Windows. Check if there is more than one environment variable set for running Python scripts in `PATH`. This usually occurs when there is more than one Python version installed. * If you are connecting to the internet behind a proxy, there might be problems in running the command `py -m pip install Django`. Set the environment variables for proxy configuration in the command prompt as follows: ``` ...\> set http_proxy=http://username:password@proxyserver:proxyport ...\> set https_proxy=https://username:password@proxyserver:proxyport ``` * In general, Django assumes that `UTF-8` encoding is used for I/O. This may cause problems if your system is set to use a different encoding. Recent versions of Python allow setting the [`PYTHONUTF8`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUTF8 "(in Python v3.15)") environment variable in order to force a `UTF-8` encoding. Windows 10 also provides a system-wide setting by checking `Use Unicode UTF-8 for worldwide language support` in Language ‣ Administrative Language Settings ‣ Change system locale in system settings. [**Back to Top](#top) ## Additional Information ### Support Django! * [Richard Cornish donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [How to install Django on Windows](#) * [Install Python](#install-python) * [About `pip`](#about-pip) * [Setting up a virtual environment](#setting-up-a-virtual-environment) * [Install Django](#install-django) * [Colored terminal output](#colored-terminal-output) * [Common pitfalls](#common-pitfalls) ---- url: https://docs.djangoproject.com/en/6.1/ref/tasks/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/tasks/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/tasks/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/tasks/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/tasks/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/tasks/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/tasks/) - [it](https://docs.djangoproject.com/it/6.1/ref/tasks/) - [id](https://docs.djangoproject.com/id/6.1/ref/tasks/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/tasks/) - [es](https://docs.djangoproject.com/es/6.1/ref/tasks/) - [el](https://docs.djangoproject.com/el/6.1/ref/tasks/) * * [dev](https://docs.djangoproject.com/en/dev/ref/tasks/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/tasks/) - [**](#top) # Tasks[¶](#tasks "Link to this heading") New in Django 6.0. The Task framework provides the contract and plumbing for background work, not the engine that runs it. The Tasks API defines how work is described, queued, and tracked, but leaves actual execution to external infrastructure. ## Task definition[¶](#task-definition "Link to this heading") ### The `task` decorator[¶](#the-task-decorator "Link to this heading") * task(*\**, *priority=0*, *queue\_name='default'*, *backend='default'*, *takes\_context=False*, *\*\*kwargs*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L151)[¶](#django.tasks.task "Link to this definition") The `@task` decorator defines a [`Task`](#django.tasks.Task "django.tasks.Task") instance. All keyword arguments are passed directly to the backend’s `task_class` (which defaults to [`Task`](#django.tasks.Task "django.tasks.Task")). The following standard arguments are supported: * `priority`: Sets the [`priority`](#django.tasks.Task.priority "django.tasks.Task.priority") of the `Task`. Defaults to 0. * `queue_name`: Sets the [`queue_name`](#django.tasks.Task.queue_name "django.tasks.Task.queue_name") of the `Task`. Defaults to `"default"`. * `backend`: Sets the [`backend`](#django.tasks.Task.backend "django.tasks.Task.backend") of the `Task`. Defaults to `"default"`. * `takes_context`: Controls whether the `Task` function accepts a [`TaskContext`](#django.tasks.TaskContext "django.tasks.TaskContext"). Defaults to `False`. See [Task context](../../topics/tasks/#task-context) for details. Custom Task backends may define a custom `task_class` that accepts additional arguments. These can be passed through the `@task` decorator: ``` @task(foo=5, bar=600) def my_task(): pass ``` Changed in Django 6.1: Support for passing arbitrary `**kwargs` to the `@task` decorator is added. If the defined `Task` is not valid according to the backend, [`InvalidTask`](#django.tasks.exceptions.InvalidTask "django.tasks.exceptions.InvalidTask") is raised. See [defining tasks](../../topics/tasks/#defining-tasks) for usage examples. ### `Task`[¶](#task "Link to this heading") * *class *Task[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L45)[¶](#django.tasks.Task "Link to this definition") Represents a Task to be run in the background. Tasks should be defined using the [`task()`](#django.tasks.task "django.tasks.task") decorator. Attributes of `Task` cannot be modified. See [modifying Tasks](../../topics/tasks/#modifying-tasks) for details. * priority[¶](#django.tasks.Task.priority "Link to this definition") The priority of the `Task`. Priorities must be between -100 and 100, where larger numbers are higher priority, and will be run sooner. The backend must have [`supports_priority`](#django.tasks.backends.base.BaseTaskBackend.supports_priority "django.tasks.backends.base.BaseTaskBackend.supports_priority") set to `True` to use this feature. - backend[¶](#django.tasks.Task.backend "Link to this definition") The alias of the backend the `Task` should be enqueued to. This must match a backend defined in [`BACKEND`](../settings/#std-setting-TASKS-BACKEND). * queue\_name[¶](#django.tasks.Task.queue_name "Link to this definition") The name of the queue the `Task` will be enqueued on to. Defaults to `"default"`. This must match a queue defined in [`QUEUES`](../settings/#std-setting-TASKS-QUEUES), unless [`QUEUES`](../settings/#std-setting-TASKS-QUEUES) is set to `[]`. - run\_after[¶](#django.tasks.Task.run_after "Link to this definition") The earliest time the `Task` will be executed. This can be a [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)"), which is used relative to the current time, a timezone-aware [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)"), or `None` if not constrained. Defaults to `None`. This attribute can be set using [`using()`](#django.tasks.Task.using "django.tasks.Task.using"). The backend must have [`supports_defer`](#django.tasks.backends.base.BaseTaskBackend.supports_defer "django.tasks.backends.base.BaseTaskBackend.supports_defer") set to `True` to use this feature. Otherwise, [`InvalidTask`](#django.tasks.exceptions.InvalidTask "django.tasks.exceptions.InvalidTask") is raised. * name[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L76)[¶](#django.tasks.Task.name "Link to this definition") The name of the function decorated with [`task()`](#django.tasks.task "django.tasks.task"). This name is not necessarily unique. - using(*\**, *priority=None*, *backend=None*, *queue\_name=None*, *run\_after=None*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L79)[¶](#django.tasks.Task.using "Link to this definition") Creates a new `Task` with modified defaults. The existing `Task` is left unchanged. `using` allows modifying the following attributes: * [`priority`](#django.tasks.Task.priority "django.tasks.Task.priority") * [`backend`](#django.tasks.Task.backend "django.tasks.Task.backend") * [`queue_name`](#django.tasks.Task.queue_name "django.tasks.Task.queue_name") * [`run_after`](#django.tasks.Task.run_after "django.tasks.Task.run_after") See [modifying Tasks](../../topics/tasks/#modifying-tasks) for usage examples. * enqueue(*\*args*, *\*\*kwargs*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L100)[¶](#django.tasks.Task.enqueue "Link to this definition") Enqueues the `Task` to the `Task` backend for later execution. Arguments are passed to the `Task`’s function after a round-trip through a [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps "(in Python v3.15)")/[`json.loads()`](https://docs.python.org/3/library/json.html#json.loads "(in Python v3.15)") cycle. Hence, all arguments must be JSON-serializable and preserve their type after the round-trip. If the `Task` is not valid according to the backend, [`InvalidTask`](#django.tasks.exceptions.InvalidTask "django.tasks.exceptions.InvalidTask") is raised. See [enqueueing Tasks](../../topics/tasks/#enqueueing-tasks) for usage examples. - aenqueue(*\*args*, *\*\*kwargs*)[¶](#django.tasks.Task.aenqueue "Link to this definition") The `async` variant of [`enqueue`](#django.tasks.Task.enqueue "django.tasks.Task.enqueue"). * get\_result(*result\_id*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L108)[¶](#django.tasks.Task.get_result "Link to this definition") Retrieves a result by its id. If the result does not exist, [`TaskResultDoesNotExist`](#django.tasks.exceptions.TaskResultDoesNotExist "django.tasks.exceptions.TaskResultDoesNotExist") is raised. If the result is not the same type as the current Task, [`TaskResultMismatch`](#django.tasks.exceptions.TaskResultMismatch "django.tasks.exceptions.TaskResultMismatch") is raised. If the backend does not support `get_result()`, [`NotImplementedError`](https://docs.python.org/3/builtins/exceptions.html#NotImplementedError "(in Python v3.15)") is raised. - aget\_result(*\*args*, *\*\*kwargs*)[¶](#django.tasks.Task.aget_result "Link to this definition") The `async` variant of [`get_result`](#django.tasks.Task.get_result "django.tasks.Task.get_result"). ## Task context[¶](#task-context "Link to this heading") * *class *TaskContext[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L267)[¶](#django.tasks.TaskContext "Link to this definition") Contains context for the running [`Task`](#django.tasks.Task "django.tasks.Task"). Context only passed to a `Task` if it was defined with `takes_context=True`. Attributes of `TaskContext` cannot be modified. * task\_result[¶](#django.tasks.TaskContext.task_result "Link to this definition") The [`TaskResult`](#django.tasks.TaskResult "django.tasks.TaskResult") currently being run. - attempt[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L271)[¶](#django.tasks.TaskContext.attempt "Link to this definition") The number of the current execution attempts for this Task, starting at 1. ## Task results[¶](#task-results "Link to this heading") * *class *TaskResultStatus[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L33)[¶](#django.tasks.TaskResultStatus "Link to this definition") An Enum representing the status of a [`TaskResult`](#django.tasks.TaskResult "django.tasks.TaskResult"). * READY[¶](#django.tasks.TaskResultStatus.READY "Link to this definition") The [`Task`](#django.tasks.Task "django.tasks.Task") has just been enqueued, or is ready to be executed again. - RUNNING[¶](#django.tasks.TaskResultStatus.RUNNING "Link to this definition") The [`Task`](#django.tasks.Task "django.tasks.Task") is currently being executed. * FAILED[¶](#django.tasks.TaskResultStatus.FAILED "Link to this definition") The [`Task`](#django.tasks.Task "django.tasks.Task") raised an exception during execution, or was unable to start. - SUCCESSFUL[¶](#django.tasks.TaskResultStatus.SUCCESSFUL "Link to this definition") The [`Task`](#django.tasks.Task "django.tasks.Task") has finished executing successfully. - *class *TaskResult[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L203)[¶](#django.tasks.TaskResult "Link to this definition") The `TaskResult` stores the information about a specific execution of a [`Task`](#django.tasks.Task "django.tasks.Task"). Attributes of `TaskResult` cannot be modified. * task[¶](#django.tasks.TaskResult.task "Link to this definition") The [`Task`](#django.tasks.Task "django.tasks.Task") the result was enqueued for. - id[¶](#django.tasks.TaskResult.id "Link to this definition") A unique identifier for the result, which can be passed to [`Task.get_result()`](#django.tasks.Task.get_result "django.tasks.Task.get_result"). The format of the id will depend on the backend being used. Task result ids are always strings less than 64 characters. See [Task results](../../topics/tasks/#task-results) for more details. * status[¶](#django.tasks.TaskResult.status "Link to this definition") The [`status`](#django.tasks.TaskResultStatus "django.tasks.TaskResultStatus") of the result. - enqueued\_at[¶](#django.tasks.TaskResult.enqueued_at "Link to this definition") The time when the `Task` was enqueued. * started\_at[¶](#django.tasks.TaskResult.started_at "Link to this definition") The time when the `Task` began execution, on its first attempt. - last\_attempted\_at[¶](#django.tasks.TaskResult.last_attempted_at "Link to this definition") The time when the most recent `Task` run began execution. * finished\_at[¶](#django.tasks.TaskResult.finished_at "Link to this definition") The time when the `Task` finished execution, whether it failed or succeeded. - backend[¶](#django.tasks.TaskResult.backend "Link to this definition") The backend the result is from. * errors[¶](#django.tasks.TaskResult.errors "Link to this definition") A list of [`TaskError`](#django.tasks.TaskError "django.tasks.TaskError") instances for the errors raised as part of each execution of the Task. - return\_value[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L228)[¶](#django.tasks.TaskResult.return_value "Link to this definition") The return value from the `Task` function. If the `Task` did not finish successfully, [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") is raised. See [return values](../../topics/tasks/#task-return-values) for usage examples. * refresh()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L250)[¶](#django.tasks.TaskResult.refresh "Link to this definition") Refresh the result’s attributes from the queue store. - arefresh()[¶](#django.tasks.TaskResult.arefresh "Link to this definition") The `async` variant of [`TaskResult.refresh()`](#django.tasks.TaskResult.refresh "django.tasks.TaskResult.refresh"). * is\_finished[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L243)[¶](#django.tasks.TaskResult.is_finished "Link to this definition") Whether the `Task` has finished (successfully or not). - attempts[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/base.py#L247)[¶](#django.tasks.TaskResult.attempts "Link to this definition") The number of times the Task has been run. If the task is currently running, it does not count as an attempt. * worker\_ids[¶](#django.tasks.TaskResult.worker_ids "Link to this definition") The ids of the workers which have executed the Task. ### Task errors[¶](#task-errors "Link to this heading") * *class *TaskError[¶](#django.tasks.TaskError "Link to this definition") Contains information about the error raised during the execution of a `Task`. * traceback[¶](#django.tasks.TaskError.traceback "Link to this definition") The traceback (as a string) from the raised exception when the `Task` failed. - exception\_class[¶](#django.tasks.TaskError.exception_class "Link to this definition") The exception class raised when executing the `Task`. ## Backends[¶](#backends "Link to this heading") Backends handle how Tasks are stored and executed. All backends share a common interface defined by `BaseTaskBackend`, which specifies the core methods for enqueueing Tasks and retrieving results. ### Base backend[¶](#module-django.tasks.backends.base "Link to this heading") * *class *BaseTaskBackend[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/backends/base.py#L19)[¶](#django.tasks.backends.base.BaseTaskBackend "Link to this definition") `BaseTaskBackend` is the parent class for all Task backends. * task\_class[¶](#django.tasks.backends.base.BaseTaskBackend.task_class "Link to this definition") The [`Task`](#django.tasks.Task "django.tasks.Task") subclass to use when creating tasks with the [`task()`](#django.tasks.task "django.tasks.task") decorator. Defaults to [`Task`](#django.tasks.Task "django.tasks.Task"). Custom backends can override this to use a custom `Task` subclass with additional attributes. - options[¶](#django.tasks.backends.base.BaseTaskBackend.options "Link to this definition") A dictionary of extra parameters for the Task backend. These are provided using the [`OPTIONS`](../settings/#std-setting-TASKS-OPTIONS) setting. * enqueue(*task*, *args*, *kwargs*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/backends/base.py#L86)[¶](#django.tasks.backends.base.BaseTaskBackend.enqueue "Link to this definition") Task backends which subclass `BaseTaskBackend` should implement this method as a minimum. When implemented, `enqueue()` enqueues the `task`, a [`Task`](#django.tasks.Task "django.tasks.Task") instance, for later execution. `args` are the positional arguments and `kwargs` are the keyword arguments to be passed to the `task`. Returns a [`TaskResult`](#django.tasks.TaskResult "django.tasks.TaskResult"). - aenqueue(*task*, *args*, *kwargs*)[¶](#django.tasks.backends.base.BaseTaskBackend.aenqueue "Link to this definition") The `async` variant of [`BaseTaskBackend.enqueue()`](#django.tasks.backends.base.BaseTaskBackend.enqueue "django.tasks.backends.base.BaseTaskBackend.enqueue"). * get\_result(*result\_id*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/backends/base.py#L95)[¶](#django.tasks.backends.base.BaseTaskBackend.get_result "Link to this definition") Retrieve a result by its id. If the result does not exist, [`TaskResultDoesNotExist`](#django.tasks.exceptions.TaskResultDoesNotExist "django.tasks.exceptions.TaskResultDoesNotExist") is raised. If the backend does not support `get_result()`, [`NotImplementedError`](https://docs.python.org/3/builtins/exceptions.html#NotImplementedError "(in Python v3.15)") is raised. - aget\_result(*result\_id*)[¶](#django.tasks.backends.base.BaseTaskBackend.aget_result "Link to this definition") The `async` variant of [`BaseTaskBackend.get_result()`](#django.tasks.backends.base.BaseTaskBackend.get_result "django.tasks.backends.base.BaseTaskBackend.get_result"). * validate\_task(*task*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/backends/base.py#L42)[¶](#django.tasks.backends.base.BaseTaskBackend.validate_task "Link to this definition") Validates whether the provided `Task` is able to be enqueued using the backend. If the Task is not valid, [`InvalidTask`](#django.tasks.exceptions.InvalidTask "django.tasks.exceptions.InvalidTask") is raised. #### Feature flags[¶](#feature-flags "Link to this heading") Some backends may not support all features Django provides. It’s possible to identify the supported functionality of a backend, and potentially change behavior accordingly. * BaseTaskBackend.supports\_defer[¶](#django.tasks.backends.base.BaseTaskBackend.supports_defer "Link to this definition") Whether the backend supports enqueueing Tasks to be executed after a specific time using the [`run_after`](#django.tasks.Task.run_after "django.tasks.Task.run_after") attribute. - BaseTaskBackend.supports\_async\_task[¶](#django.tasks.backends.base.BaseTaskBackend.supports_async_task "Link to this definition") Whether the backend supports enqueueing async functions (coroutines). * BaseTaskBackend.supports\_get\_result[¶](#django.tasks.backends.base.BaseTaskBackend.supports_get_result "Link to this definition") Whether the backend supports retrieving `Task` results from another thread after they have been enqueued. - BaseTaskBackend.supports\_priority[¶](#django.tasks.backends.base.BaseTaskBackend.supports_priority "Link to this definition") Whether the backend supports executing Tasks as ordered by their [`priority`](#django.tasks.Task.priority "django.tasks.Task.priority"). The below table notes which of the [built-in backends](#task-available-backends) support which features: | Feature | [`DummyBackend`](#django.tasks.backends.dummy.DummyBackend "django.tasks.backends.dummy.DummyBackend") | [`ImmediateBackend`](#django.tasks.backends.immediate.ImmediateBackend "django.tasks.backends.immediate.ImmediateBackend") | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | [`supports_defer`](#django.tasks.backends.base.BaseTaskBackend.supports_defer "django.tasks.backends.base.BaseTaskBackend.supports_defer") | Yes | No | | [`supports_async_task`](#django.tasks.backends.base.BaseTaskBackend.supports_async_task "django.tasks.backends.base.BaseTaskBackend.supports_async_task") | Yes | Yes | | [`supports_get_result`](#django.tasks.backends.base.BaseTaskBackend.supports_get_result "django.tasks.backends.base.BaseTaskBackend.supports_get_result") | No | No [\[1\]](#fnimmediateresult) | | [`supports_priority`](#django.tasks.backends.base.BaseTaskBackend.supports_priority "django.tasks.backends.base.BaseTaskBackend.supports_priority") | Yes [\[2\]](#fndummypriority) | Yes [\[3\]](#fnimmediatepriority) | ### Available backends[¶](#available-backends "Link to this heading") Django includes only development and testing backends. These support local execution and inspection, for production ready backends refer to [Configuring a Task backend](../../topics/tasks/#configuring-a-task-backend). #### Immediate backend[¶](#module-django.tasks.backends.immediate "Link to this heading") * *class *ImmediateBackend[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/backends/immediate.py#L15)[¶](#django.tasks.backends.immediate.ImmediateBackend "Link to this definition") The [immediate backend](../../topics/tasks/#immediate-task-backend) executes Tasks immediately, rather than in the background. #### Dummy backend[¶](#module-django.tasks.backends.dummy "Link to this heading") * *class *DummyBackend[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/backends/dummy.py#L12)[¶](#django.tasks.backends.dummy.DummyBackend "Link to this definition") The [dummy backend](../../topics/tasks/#dummy-task-backend) does not execute enqueued Tasks. Instead, it stores task results for later inspection. * results[¶](#django.tasks.backends.dummy.DummyBackend.results "Link to this definition") A list of results for the enqueued Tasks, in the order they were enqueued. - clear()[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/backends/dummy.py#L63)[¶](#django.tasks.backends.dummy.DummyBackend.clear "Link to this definition") Clears the list of stored results. ## Exceptions[¶](#module-django.tasks.exceptions "Link to this heading") * *exception *InvalidTask[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/exceptions.py#L8)[¶](#django.tasks.exceptions.InvalidTask "Link to this definition") Raised when the [`Task`](#django.tasks.Task "django.tasks.Task") attempting to be enqueued is invalid. - *exception *InvalidTaskBackend[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/exceptions.py#L12)[¶](#django.tasks.exceptions.InvalidTaskBackend "Link to this definition") Raised when the requested [`BaseTaskBackend`](#django.tasks.backends.base.BaseTaskBackend "django.tasks.backends.base.BaseTaskBackend") is invalid. * *exception *TaskResultDoesNotExist[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/exceptions.py#L16)[¶](#django.tasks.exceptions.TaskResultDoesNotExist "Link to this definition") Raised by [`get_result()`](#django.tasks.backends.base.BaseTaskBackend.get_result "django.tasks.backends.base.BaseTaskBackend.get_result") when the provided `result_id` does not exist. - *exception *TaskResultMismatch[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/tasks/exceptions.py#L20)[¶](#django.tasks.exceptions.TaskResultMismatch "Link to this definition") Raised by [`get_result()`](#django.tasks.Task.get_result "django.tasks.Task.get_result") when the provided `result_id` is for a different Task than the current Task. Footnotes [**Back to Top](#top) ## Additional Information ### Support Django! * [Albertus Engelbrecht donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Tasks](#) * [Task definition](#task-definition) * [The `task` decorator](#the-task-decorator) * [`Task`](#task) * [Task context](#task-context) * [Task results](#task-results) * [Task errors](#task-errors) * [Backends](#backends) * [Base backend](#module-django.tasks.backends.base) * [Feature flags](#feature-flags) * [Available backends](#available-backends) * [Immediate backend](#module-django.tasks.backends.immediate) * [Dummy backend](#module-django.tasks.backends.dummy) * [Exceptions](#module-django.tasks.exceptions) ---- url: https://docs.djangoproject.com/en/6.1/ref/contrib/gis/ogrinspect/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/ref/contrib/gis/ogrinspect/) - [sv](https://docs.djangoproject.com/sv/6.1/ref/contrib/gis/ogrinspect/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/ref/contrib/gis/ogrinspect/) - [pl](https://docs.djangoproject.com/pl/6.1/ref/contrib/gis/ogrinspect/) - [ko](https://docs.djangoproject.com/ko/6.1/ref/contrib/gis/ogrinspect/) - [ja](https://docs.djangoproject.com/ja/6.1/ref/contrib/gis/ogrinspect/) - [it](https://docs.djangoproject.com/it/6.1/ref/contrib/gis/ogrinspect/) - [id](https://docs.djangoproject.com/id/6.1/ref/contrib/gis/ogrinspect/) - [fr](https://docs.djangoproject.com/fr/6.1/ref/contrib/gis/ogrinspect/) - [es](https://docs.djangoproject.com/es/6.1/ref/contrib/gis/ogrinspect/) - [el](https://docs.djangoproject.com/el/6.1/ref/contrib/gis/ogrinspect/) * * [dev](https://docs.djangoproject.com/en/dev/ref/contrib/gis/ogrinspect/) * [6.0](https://docs.djangoproject.com/en/6.0/ref/contrib/gis/ogrinspect/) * [5.2](https://docs.djangoproject.com/en/5.2/ref/contrib/gis/ogrinspect/) * [5.1](https://docs.djangoproject.com/en/5.1/ref/contrib/gis/ogrinspect/) * [5.0](https://docs.djangoproject.com/en/5.0/ref/contrib/gis/ogrinspect/) * [4.2](https://docs.djangoproject.com/en/4.2/ref/contrib/gis/ogrinspect/) * [4.1](https://docs.djangoproject.com/en/4.1/ref/contrib/gis/ogrinspect/) * [4.0](https://docs.djangoproject.com/en/4.0/ref/contrib/gis/ogrinspect/) * [3.2](https://docs.djangoproject.com/en/3.2/ref/contrib/gis/ogrinspect/) * [3.1](https://docs.djangoproject.com/en/3.1/ref/contrib/gis/ogrinspect/) * [3.0](https://docs.djangoproject.com/en/3.0/ref/contrib/gis/ogrinspect/) * [2.2](https://docs.djangoproject.com/en/2.2/ref/contrib/gis/ogrinspect/) * [2.1](https://docs.djangoproject.com/en/2.1/ref/contrib/gis/ogrinspect/) * [2.0](https://docs.djangoproject.com/en/2.0/ref/contrib/gis/ogrinspect/) * [1.11](https://docs.djangoproject.com/en/1.11/ref/contrib/gis/ogrinspect/) * [1.10](https://docs.djangoproject.com/en/1.10/ref/contrib/gis/ogrinspect/) * [1.9](https://docs.djangoproject.com/en/1.9/ref/contrib/gis/ogrinspect/) * [1.8](https://docs.djangoproject.com/en/1.8/ref/contrib/gis/ogrinspect/) - [**](#top) # OGR Inspection[¶](#module-django.contrib.gis.utils.ogrinspect "Link to this heading") ## `ogrinspect`[¶](#ogrinspect "Link to this heading") * ogrinspect(*data\_source*, *model\_name*, *\*\*kwargs*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/utils/ogrinspect.py#L59) ## `mapping`[¶](#mapping "Link to this heading") * mapping(*data\_source*, *geom\_name='geom'*, *layer\_key=0*, *multi\_geom=False*)[\[source\]](https://github.com/django/django/blob/stable/6.1.x/django/contrib/gis/utils/ogrinspect.py#L19)[¶](#django.contrib.gis.utils.mapping "Link to this definition") [**Back to Top](#top) ## Additional Information ### Support Django! * [X-Net Services GmbH donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [OGR Inspection](#) * [`ogrinspect`](#ogrinspect) * [`mapping`](#mapping) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.2.6/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.2.6/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.2.6/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.2.6/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.2.6/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.2.6/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.2.6/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.2.6/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.2.6/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.2.6/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.2.6/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.2.6/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.2.6/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.2.6/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.2.6/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.2.6/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.2.6/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.2.6/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.2.6/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.2.6/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.2.6/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.2.6/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.2.6/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.2.6/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.2.6/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.2.6/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.2.6/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.2.6/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.2.6/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.2.6/) - [**](#top) # Django 1.2.6 release notes[¶](#django-1-2-6-release-notes "Link to this heading") *September 9, 2011* Welcome to Django 1.2.6! This is the sixth bugfix/security release in the Django 1.2 series, fixing several security issues present in Django 1.2.5. Django 1.2.6 is a recommended upgrade for all users of any Django release in the 1.2.X series. For a full list of issues addressed in this release, see the [security advisory](https://www.djangoproject.com/weblog/2011/sep/09/security-releases-issued/). [**Back to Top](#top) ## Additional Information ### Support Django! * [Ask Company donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.2.6 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.11.6/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.11.6/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.11.6/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.11.6/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.11.6/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.11.6/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.11.6/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.11.6/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.11.6/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.11.6/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.11.6/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.11.6/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.11.6/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.11.6/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.11.6/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.11.6/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.11.6/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.11.6/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.11.6/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.11.6/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.11.6/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.11.6/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.11.6/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.11.6/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.11.6/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.11.6/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.11.6/) - [**](#top) # Django 1.11.6 release notes[¶](#django-1-11-6-release-notes "Link to this heading") *October 5, 2017* Django 1.11.6 fixes several bugs in 1.11.5. ## Bugfixes[¶](#bugfixes "Link to this heading") * Made the `CharField` form field convert whitespace-only values to the `empty_value` when `strip` is enabled ([#28555](https://code.djangoproject.com/ticket/28555)). * Fixed crash when using the name of a model’s autogenerated primary key (`id`) in an `Index`’s `fields` ([#28597](https://code.djangoproject.com/ticket/28597)). * Fixed a regression in Django 1.9 where a custom view error handler such as `handler404` that accesses `csrf_token` could cause CSRF verification failures on other pages ([#28488](https://code.djangoproject.com/ticket/28488)). [**Back to Top](#top) ## Additional Information ### Support Django! * [Perlet & Shiner, P.A. donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.11.6 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/releases/3.1.12/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/3.1.12/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/3.1.12/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/3.1.12/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/3.1.12/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/3.1.12/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/3.1.12/) - [it](https://docs.djangoproject.com/it/6.1/releases/3.1.12/) - [id](https://docs.djangoproject.com/id/6.1/releases/3.1.12/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/3.1.12/) - [es](https://docs.djangoproject.com/es/6.1/releases/3.1.12/) - [el](https://docs.djangoproject.com/el/6.1/releases/3.1.12/) * * [dev](https://docs.djangoproject.com/en/dev/releases/3.1.12/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/3.1.12/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/3.1.12/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/3.1.12/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/3.1.12/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/3.1.12/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/3.1.12/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/3.1.12/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/3.1.12/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/3.1.12/) - [**](#top) # Django 3.1.12 release notes[¶](#django-3-1-12-release-notes "Link to this heading") *June 2, 2021* Django 3.1.12 fixes two security issues in 3.1.11. * [Nicolas Dubois donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 3.1.12 release notes](#) ---- url: https://docs.djangoproject.com/en/6.1/topics/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/) - [it](https://docs.djangoproject.com/it/6.1/topics/) - [id](https://docs.djangoproject.com/id/6.1/topics/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/) - [es](https://docs.djangoproject.com/es/6.1/topics/) - [el](https://docs.djangoproject.com/el/6.1/topics/) * * [dev](https://docs.djangoproject.com/en/dev/topics/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/) * [5.2](https://docs.djangoproject.com/en/5.2/topics/) * [5.1](https://docs.djangoproject.com/en/5.1/topics/) * [5.0](https://docs.djangoproject.com/en/5.0/topics/) * [4.2](https://docs.djangoproject.com/en/4.2/topics/) * [4.1](https://docs.djangoproject.com/en/4.1/topics/) * [4.0](https://docs.djangoproject.com/en/4.0/topics/) * [3.2](https://docs.djangoproject.com/en/3.2/topics/) * [3.1](https://docs.djangoproject.com/en/3.1/topics/) * [3.0](https://docs.djangoproject.com/en/3.0/topics/) * [2.2](https://docs.djangoproject.com/en/2.2/topics/) * [2.1](https://docs.djangoproject.com/en/2.1/topics/) * [2.0](https://docs.djangoproject.com/en/2.0/topics/) * [1.11](https://docs.djangoproject.com/en/1.11/topics/) * [1.10](https://docs.djangoproject.com/en/1.10/topics/) * [1.9](https://docs.djangoproject.com/en/1.9/topics/) * [1.8](https://docs.djangoproject.com/en/1.8/topics/) - [**](#top) # Using Django[¶](#using-django "Link to this heading") Introductions to all the key parts of Django you’ll need to know: * [How to install Django](install/) * [Install Python](install/#install-python) * [Install Apache and `mod_wsgi`](install/#install-apache-and-mod-wsgi) * [Get your database running](install/#get-your-database-running) * [Install the Django code](install/#install-the-django-code) * [Models and databases](db/) * [Models](db/models/) * [Making queries](db/queries/) * [Fetch modes](db/fetch-modes/) * [Aggregation](db/aggregation/) * [Search](db/search/) * [Managers](db/managers/) * [Performing raw SQL queries](db/sql/) * [Database transactions](db/transactions/) * [Multiple databases](db/multi-db/) * [Tablespaces](db/tablespaces/) * [Database access optimization](db/optimization/) * [Database instrumentation](db/instrumentation/) * [Fixtures](db/fixtures/) * [Examples of model relationship API usage](db/examples/) * [Handling HTTP requests](http/) * [URL dispatcher](http/urls/) * [Writing views](http/views/) * [View decorators](http/decorators/) * [File Uploads](http/file-uploads/) * [Django shortcut functions](http/shortcuts/) * [Generic views](http/generic-views/) * [Middleware](http/middleware/) * [How to use sessions](http/sessions/) * [Working with forms](forms/) * [HTML forms](forms/#html-forms) * [Django’s role in forms](forms/#django-s-role-in-forms) * [Forms in Django](forms/#forms-in-django) * [Building a form](forms/#building-a-form) * [More about Django `Form` classes](forms/#more-about-django-form-classes) * [Working with form templates](forms/#working-with-form-templates) * [Further topics](forms/#further-topics) * [Templates](templates/) * [The Django template language](templates/#the-django-template-language) * [Support for template engines](templates/#support-for-template-engines) * [Class-based views](class-based-views/) * [Introduction to class-based views](class-based-views/intro/) * [Built-in class-based generic views](class-based-views/generic-display/) * [Form handling with class-based views](class-based-views/generic-editing/) * [Using mixins with class-based views](class-based-views/mixins/) * [Basic examples](class-based-views/#basic-examples) * [Usage in your URLconf](class-based-views/#usage-in-your-urlconf) * [Subclassing generic views](class-based-views/#subclassing-generic-views) * [Asynchronous class-based views](class-based-views/#asynchronous-class-based-views) * [Migrations](migrations/) * [The Commands](migrations/#the-commands) * [Backend Support](migrations/#backend-support) * [Workflow](migrations/#workflow) * [Transactions](migrations/#transactions) * [Dependencies](migrations/#dependencies) * [Migration files](migrations/#migration-files) * [Adding migrations to apps](migrations/#adding-migrations-to-apps) * [Reversing migrations](migrations/#reversing-migrations) * [Historical models](migrations/#historical-models) * [Considerations when removing model fields](migrations/#considerations-when-removing-model-fields) * [Data Migrations](migrations/#data-migrations) * [Squashing migrations](migrations/#squashing-migrations) * [Serializing values](migrations/#serializing-values) * [Supporting multiple Django versions](migrations/#supporting-multiple-django-versions) * [Managing files](files/) * [Using files in models](files/#using-files-in-models) * [The `File` object](files/#the-file-object) * [File storage](files/#file-storage) * [Testing in Django](testing/) * [Writing and running tests](testing/overview/) * [Testing tools](testing/tools/) * [Advanced testing topics](testing/advanced/) * [User authentication in Django](auth/) * [Overview](auth/#overview) * [Installation](auth/#installation) * [Usage](auth/#usage) * [Django’s cache framework](cache/) * [Setting up the cache](cache/#setting-up-the-cache) * [The per-site cache](cache/#the-per-site-cache) * [The per-view cache](cache/#the-per-view-cache) * [Template fragment caching](cache/#template-fragment-caching) * [The low-level cache API](cache/#the-low-level-cache-api) * [Asynchronous support](cache/#asynchronous-support) * [Downstream caches](cache/#downstream-caches) * [Using `Vary` headers](cache/#using-vary-headers) * [Controlling cache: Using other headers](cache/#controlling-cache-using-other-headers) * [Order of `MIDDLEWARE`](cache/#order-of-middleware) * [Conditional View Processing](conditional-view-processing/) * [The `condition` decorator](conditional-view-processing/#the-condition-decorator) * [Shortcuts for only computing one value](conditional-view-processing/#shortcuts-for-only-computing-one-value) * [Using the decorators with other HTTP methods](conditional-view-processing/#using-the-decorators-with-other-http-methods) * [Comparison with middleware conditional processing](conditional-view-processing/#comparison-with-middleware-conditional-processing) * [Composite primary keys](composite-primary-key/) * [Migrating to a composite primary key](composite-primary-key/#migrating-to-a-composite-primary-key) * [Composite primary keys and relations](composite-primary-key/#composite-primary-keys-and-relations) * [Composite primary keys and database functions](composite-primary-key/#composite-primary-keys-and-database-functions) * [Composite primary keys in forms](composite-primary-key/#composite-primary-keys-in-forms) * [Composite primary keys in model validation](composite-primary-key/#composite-primary-keys-in-model-validation) * [Building composite primary key ready applications](composite-primary-key/#building-composite-primary-key-ready-applications) * [Cryptographic signing](signing/) * [Protecting `SECRET_KEY` and `SECRET_KEY_FALLBACKS`](signing/#protecting-secret-key-and-secret-key-fallbacks) * [Using the low-level API](signing/#using-the-low-level-api) * [Sending email](email/) * [Quick examples](email/#quick-examples) * [Configuring email](email/#configuring-email) * [Sending messages](email/#sending-messages) * [Email backends](email/#email-backends) * [Configuring email for development](email/#configuring-email-for-development) * [Internationalization and localization](i18n/) * [Overview](i18n/#overview) * [Definitions](i18n/#definitions) * [Logging](logging/) * [Overview](logging/#overview) * [Security implications](logging/#security-implications) * [Configuring logging](logging/#configuring-logging) * [Pagination](pagination/) * [The `Paginator` class](pagination/#the-paginator-class) * [Example](pagination/#example) * [Paginating a `ListView`](pagination/#paginating-a-listview) * [Using `Paginator` in a view function](pagination/#using-paginator-in-a-view-function) * [Security in Django](security/) * [Always sanitize user input](security/#always-sanitize-user-input) * [Cross-site scripting (XSS) protection](security/#cross-site-scripting-xss-protection) * [Cross-site request forgery (CSRF) protection](security/#cross-site-request-forgery-csrf-protection) * [SQL injection protection](security/#sql-injection-protection) * [Clickjacking protection](security/#clickjacking-protection) * [SSL/HTTPS](security/#ssl-https) * [Host header validation](security/#host-header-validation) * [Referrer policy](security/#referrer-policy) * [Cross-origin opener policy](security/#cross-origin-opener-policy) * [Cross-origin resource sharing (CORS)](security/#cross-origin-resource-sharing-cors) * [Session security](security/#session-security) * [User-uploaded content](security/#user-uploaded-content) * [Form Submissions](security/#form-submissions) * [Content Security Policy](security/#content-security-policy) * [Additional security topics](security/#additional-security-topics) * [Performance and optimization](performance/) * [Introduction](performance/#introduction) * [General approaches](performance/#general-approaches) * [Caching](performance/#caching) * [Understanding laziness](performance/#understanding-laziness) * [Databases](performance/#databases) * [HTTP performance](performance/#http-performance) * [Template performance](performance/#template-performance) * [Using different versions of available software](performance/#using-different-versions-of-available-software) * [Serializing Django objects](serialization/) * [Serializing data](serialization/#serializing-data) * [Deserializing data](serialization/#deserializing-data) * [Serialization formats](serialization/#serialization-formats) * [Natural keys](serialization/#natural-keys) * [Django settings](settings/) * [The basics](settings/#the-basics) * [Designating the settings](settings/#designating-the-settings) * [Default settings](settings/#default-settings) * [Using settings in Python code](settings/#using-settings-in-python-code) * [Altering settings at runtime](settings/#altering-settings-at-runtime) * [Security](settings/#security) * [Available settings](settings/#available-settings) * [Creating your own settings](settings/#creating-your-own-settings) * [Using settings without setting `DJANGO_SETTINGS_MODULE`](settings/#using-settings-without-setting-django-settings-module) * [Signals](signals/) * [Listening to signals](signals/#listening-to-signals) * [Defining and sending signals](signals/#defining-and-sending-signals) * [Disconnecting signals](signals/#disconnecting-signals) * [System check framework](checks/) * [Writing your own checks](checks/#writing-your-own-checks) * [Asynchronous support](async/) * [Async views](async/#async-views) * [Async safety](async/#async-safety) * [Async adapter functions](async/#async-adapter-functions) * [Django’s Tasks framework](tasks/) * [Background Task fundamentals](tasks/#background-task-fundamentals) * [Configuring a Task backend](tasks/#configuring-a-task-backend) * [Defining Tasks](tasks/#defining-tasks) * [Enqueueing Tasks](tasks/#enqueueing-tasks) * [Task results](tasks/#task-results) [**Back to Top](#top) ## Additional Information ### Support Django! * [Fridrik Juliusson donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Using Django](#) ---- url: https://docs.djangoproject.com/en/6.1/topics/tasks/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/topics/tasks/) - [sv](https://docs.djangoproject.com/sv/6.1/topics/tasks/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/topics/tasks/) - [pl](https://docs.djangoproject.com/pl/6.1/topics/tasks/) - [ko](https://docs.djangoproject.com/ko/6.1/topics/tasks/) - [ja](https://docs.djangoproject.com/ja/6.1/topics/tasks/) - [it](https://docs.djangoproject.com/it/6.1/topics/tasks/) - [id](https://docs.djangoproject.com/id/6.1/topics/tasks/) - [fr](https://docs.djangoproject.com/fr/6.1/topics/tasks/) - [es](https://docs.djangoproject.com/es/6.1/topics/tasks/) - [el](https://docs.djangoproject.com/el/6.1/topics/tasks/) * * [dev](https://docs.djangoproject.com/en/dev/topics/tasks/) * [6.0](https://docs.djangoproject.com/en/6.0/topics/tasks/) - [**](#top) # Django’s Tasks framework[¶](#django-s-tasks-framework "Link to this heading") New in Django 6.0: For older Django versions, the [django-tasks](https://pypi.org/project/django-tasks/) backport is available. For a web application, there’s often more than just turning HTTP requests into HTTP responses. For some functionality, it may be beneficial to run code outside the request-response cycle. That’s where background Tasks come in. Background Tasks can offload work to be run outside the request-response cycle, to be run elsewhere, potentially at a later date. This keeps requests fast, reduces latency, and improves the user experience. For example, a user shouldn’t have to wait for an email to send before their page finishes loading. Django’s Tasks framework makes it easy to define and enqueue such work. It does not provide a worker mechanism to run Tasks. The actual execution must be handled by infrastructure outside Django, such as a separate process or service. Given that, a [task backend](#configuring-a-task-backend) capable of executing tasks on that service should be evaluated and configured. ## Background Task fundamentals[¶](#background-task-fundamentals "Link to this heading") When work needs to be done in the background, Django creates a `Task`, which is stored in the Queue Store. This `Task` contains all the metadata needed to execute it, as well as a unique identifier for Django to retrieve the result later. A Worker will look at the Queue Store for new Tasks to run. When a new Task is added, a Worker claims the Task, executes it, and saves the status and result back to the Queue Store. These workers run outside the request-response lifecycle. ## Configuring a Task backend[¶](#configuring-a-task-backend "Link to this heading") The Task backend determines how and where Tasks are stored for execution and how they are executed. Different Task backends have different characteristics and configuration options, which may impact the performance and reliability of your application. Django comes with [built-in backends](../../ref/tasks/#task-available-backends), but these are for development and testing only. Django handles task definition, validation, queuing, and result handling, not execution, so production setups need a backend or worker process that actually runs queued work. Relevant options are listed in the [Community Ecosystem](https://www.djangoproject.com/community/ecosystem/) page. Task backends are configured using the [`TASKS`](../../ref/settings/#std-setting-TASKS) setting in your settings file. Whilst most applications will only need a single backend, multiple are supported. ### Immediate execution[¶](#immediate-execution "Link to this heading") This is the default backend if another is not specified in your settings file. The [`ImmediateBackend`](../../ref/tasks/#django.tasks.backends.immediate.ImmediateBackend "django.tasks.backends.immediate.ImmediateBackend") runs enqueued Tasks immediately, rather than in the background. This allows background Task functionality to be slowly added to an application, before the required infrastructure is available. To use it, set [`BACKEND`](../../ref/settings/#std-setting-TASKS-BACKEND) to `"django.tasks.backends.immediate.ImmediateBackend"`: ``` TASKS = {"default": {"BACKEND": "django.tasks.backends.immediate.ImmediateBackend"}} ``` The [`ImmediateBackend`](../../ref/tasks/#django.tasks.backends.immediate.ImmediateBackend "django.tasks.backends.immediate.ImmediateBackend") may also be useful in tests, to bypass the need to run a real background worker in your tests. ### Dummy backend[¶](#dummy-backend "Link to this heading") The [`DummyBackend`](../../ref/tasks/#django.tasks.backends.dummy.DummyBackend "django.tasks.backends.dummy.DummyBackend") doesn’t execute enqueued Tasks at all, instead storing results for later use. Task results will forever remain in the [`READY`](../../ref/tasks/#django.tasks.TaskResultStatus.READY "django.tasks.TaskResultStatus.READY") state. This backend is not intended for use in production - it is provided as a convenience that can be used during development and testing. To use it, set [`BACKEND`](../../ref/settings/#std-setting-TASKS-BACKEND) to `"django.tasks.backends.dummy.DummyBackend"`: ``` TASKS = {"default": {"BACKEND": "django.tasks.backends.dummy.DummyBackend"}} ``` The results for enqueued Tasks can be retrieved from the backend’s [`results`](../../ref/tasks/#django.tasks.backends.dummy.DummyBackend.results "django.tasks.backends.dummy.DummyBackend.results") attribute: ``` >>> from django.tasks import default_task_backend >>> my_task.enqueue() >>> len(default_task_backend.results) 1 ``` Stored results can be cleared using the [`clear()`](../../ref/tasks/#django.tasks.backends.dummy.DummyBackend.clear "django.tasks.backends.dummy.DummyBackend.clear") method: ``` >>> default_task_backend.clear() >>> len(default_task_backend.results) 0 ``` ### Third-party backends[¶](#third-party-backends "Link to this heading") As mentioned at the beginning of this section, Django includes backends suitable for development and testing only. Production systems should rely on backends that supply a worker process and a durable queue implementation. Available third-party backends are listed on the [Community Ecosystem page](https://www.djangoproject.com/community/ecosystem/#tasks) and the [Tasks framework grid from Django Packages](https://djangopackages.org/grids/g/task-framework/). To use an external Task backend with Django, use the Python import path as the [`BACKEND`](../../ref/settings/#std-setting-TASKS-BACKEND) of the [`TASKS`](../../ref/settings/#std-setting-TASKS) setting, like so: ``` TASKS = { "default": { "BACKEND": "path.to.backend", } } ``` A Task backend is a class that inherits [`BaseTaskBackend`](../../ref/tasks/#django.tasks.backends.base.BaseTaskBackend "django.tasks.backends.base.BaseTaskBackend"). At a minimum, it must implement [`BaseTaskBackend.enqueue()`](../../ref/tasks/#django.tasks.backends.base.BaseTaskBackend.enqueue "django.tasks.backends.base.BaseTaskBackend.enqueue"). If you’re building your own backend, you can use the built-in Task backends as reference implementations. You’ll find the code in the [django/tasks/backends/](https://github.com/django/django/blob/main/django/tasks/backends/) directory of the Django source. ### Asynchronous support[¶](#asynchronous-support "Link to this heading") Django has developing support for asynchronous Task backends. [`BaseTaskBackend`](../../ref/tasks/#django.tasks.backends.base.BaseTaskBackend "django.tasks.backends.base.BaseTaskBackend") has async variants of all base methods. By convention, the asynchronous versions of all methods are prefixed with `a`. The arguments for both variants are the same. ### Retrieving backends[¶](#retrieving-backends "Link to this heading") Backends can be retrieved using the `task_backends` connection handler: ``` from django.tasks import task_backends task_backends["default"] # The default backend task_backends["reserve"] # Another backend ``` The “default” backend is available as `default_task_backend`: ``` from django.tasks import default_task_backend ``` ## Defining Tasks[¶](#defining-tasks "Link to this heading") Tasks are defined using the [`django.tasks.task()`](../../ref/tasks/#django.tasks.task "django.tasks.task") decorator on a module-level function: ``` from django.core.mail import send_mail from django.tasks import task @task def email_users(emails, subject, message): return send_mail( subject=subject, message=message, from_email=None, recipient_list=emails ) ``` The return value of the decorator is a [`Task`](../../ref/tasks/#django.tasks.Task "django.tasks.Task") instance. [`Task`](../../ref/tasks/#django.tasks.Task "django.tasks.Task") attributes can be customized via the `@task` decorator arguments: ``` from django.core.mail import send_mail from django.tasks import task @task(priority=2, queue_name="emails") def email_users(emails, subject, message): return send_mail( subject=subject, message=message, from_email=None, recipient_list=emails ) ``` By convention, Tasks are defined in a `tasks.py` file, however this is not enforced. ### Task context[¶](#task-context "Link to this heading") Sometimes, the running `Task` may need to know context about how it was enqueued, and how it is being executed. This can be accessed by taking a `context` argument, which is an instance of [`TaskContext`](../../ref/tasks/#django.tasks.TaskContext "django.tasks.TaskContext"). To receive the Task context as an argument to your Task function, pass `takes_context` when defining it: ``` import logging from django.core.mail import send_mail from django.tasks import task logger = logging.getLogger(__name__) @task(takes_context=True) def email_users(context, emails, subject, message): logger.debug( f"Attempt {context.attempt} to send user email. Task result id: {context.task_result.id}." ) return send_mail( subject=subject, message=message, from_email=None, recipient_list=emails ) ``` ### Modifying Tasks[¶](#modifying-tasks "Link to this heading") Before enqueueing Tasks, it may be necessary to modify certain parameters of the Task. For example, to give it a higher priority than it would normally. A `Task` instance cannot be modified directly. Instead, a modified instance can be created with the [`using()`](../../ref/tasks/#django.tasks.Task.using "django.tasks.Task.using") method, leaving the original as-is. For example: ``` >>> email_users.priority 0 >>> email_users.using(priority=10).priority 10 ``` ## Enqueueing Tasks[¶](#enqueueing-tasks "Link to this heading") To add the Task to the queue store, so it will be executed, call the [`enqueue()`](../../ref/tasks/#django.tasks.Task.enqueue "django.tasks.Task.enqueue") method on it. If the Task takes arguments, these can be passed as-is. For example: ``` result = email_users.enqueue( emails=["user@example.com"], subject="You have a message", message="Hello there!", ) ``` This returns a [`TaskResult`](../../ref/tasks/#django.tasks.TaskResult "django.tasks.TaskResult"), which can be used to retrieve the result of the Task once it has finished executing. To enqueue Tasks in an `async` context, [`aenqueue()`](../../ref/tasks/#django.tasks.Task.aenqueue "django.tasks.Task.aenqueue") is available as an `async` variant of [`enqueue()`](../../ref/tasks/#django.tasks.Task.enqueue "django.tasks.Task.enqueue"). Because both Task arguments and return values are serialized to JSON, they must be JSON-serializable: ``` >>> process_data.enqueue(datetime.now()) Traceback (most recent call last): ... TypeError: Object of type datetime is not JSON serializable ``` Arguments must also be able to round-trip through a [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps "(in Python v3.15)")/ [`json.loads()`](https://docs.python.org/3/library/json.html#json.loads "(in Python v3.15)") cycle without changing type. For example, consider this Task: ``` @task() def double_dictionary(key): return {key: key * 2} ``` With the `ImmediateBackend` configured as the default backend: ``` >>> result = double_dictionary.enqueue((1, 2, 3)) >>> result.status FAILED >>> result.errors[0].traceback Traceback (most recent call last): ... TypeError: unhashable type: 'list' ``` The `double_dictionary` Task fails because after the JSON round-trip the tuple `(1, 2, 3)` becomes the list `[1, 2, 3]`, which cannot be used as a dictionary key. In general, complex objects such as model instances, or built-in types like `datetime` and `tuple` cannot be used in Tasks without additional conversion. ### Transactions[¶](#transactions "Link to this heading") For most backends, Tasks are run in a separate process, using a different database connection. When using a transaction, without waiting for it to commit, workers could start to process a Task which uses objects it can’t access yet. For example, consider this simplified example: ``` @task def my_task(thing_num): Thing.objects.get(num=thing_num) with transaction.atomic(): Thing.objects.create(num=1) my_task.enqueue(thing_num=1) ``` To prevent the scenario where `my_task` runs before the `Thing` is committed to the database, use [`transaction.on_commit()`](../db/transactions/#django.db.transaction.on_commit "django.db.transaction.on_commit"), binding all arguments to [`enqueue()`](../../ref/tasks/#django.tasks.Task.enqueue "django.tasks.Task.enqueue") via [`functools.partial()`](https://docs.python.org/3/library/functools.html#functools.partial "(in Python v3.15)"): ``` from functools import partial from django.db import transaction with transaction.atomic(): Thing.objects.create(num=1) transaction.on_commit(partial(my_task.enqueue, thing_num=1)) ``` ## Task results[¶](#task-results "Link to this heading") When enqueueing a `Task`, you receive a [`TaskResult`](../../ref/tasks/#django.tasks.TaskResult "django.tasks.TaskResult"), however it’s likely useful to retrieve the result from somewhere else (for example another request or another Task). Each `TaskResult` has a unique [`id`](../../ref/tasks/#django.tasks.TaskResult.id "django.tasks.TaskResult.id"), which can be used to identify and retrieve the result once the code which enqueued the Task has finished. The [`get_result()`](../../ref/tasks/#django.tasks.Task.get_result "django.tasks.Task.get_result") method can retrieve a result based on its `id`: ``` # Later, somewhere else... result = email_users.get_result(result_id) ``` To retrieve a `TaskResult`, regardless of which kind of `Task` it was from, use the [`get_result()`](../../ref/tasks/#django.tasks.Task.get_result "django.tasks.Task.get_result") method on the backend: ``` from django.tasks import default_task_backend result = default_task_backend.get_result(result_id) ``` To retrieve results in an `async` context, [`aget_result()`](../../ref/tasks/#django.tasks.Task.aget_result "django.tasks.Task.aget_result") is available as an `async` variant of [`get_result()`](../../ref/tasks/#django.tasks.Task.get_result "django.tasks.Task.get_result") on both the backend and `Task`. Some backends, such as the built-in `ImmediateBackend` do not support `get_result()`. Calling `get_result()` on these backends will raise [`NotImplementedError`](https://docs.python.org/3/builtins/exceptions.html#NotImplementedError "(in Python v3.15)"). ### Updating results[¶](#updating-results "Link to this heading") A `TaskResult` contains the status of a Task’s execution at the point it was retrieved. If the Task finishes after [`get_result()`](../../ref/tasks/#django.tasks.Task.get_result "django.tasks.Task.get_result") is called, it will not update. To refresh the values, call the [`django.tasks.TaskResult.refresh()`](../../ref/tasks/#django.tasks.TaskResult.refresh "django.tasks.TaskResult.refresh") method: ``` >>> result.status RUNNING >>> result.refresh() # or await result.arefresh() >>> result.status SUCCESSFUL ``` ### Return values[¶](#return-values "Link to this heading") If your Task function returns something, it can be retrieved from the [`django.tasks.TaskResult.return_value`](../../ref/tasks/#django.tasks.TaskResult.return_value "django.tasks.TaskResult.return_value") attribute: ``` >>> result.status SUCCESSFUL >>> result.return_value 42 ``` If the Task has not finished executing, or has failed, [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") is raised. ``` >>> result.status RUNNING >>> result.return_value Traceback (most recent call last): ... ValueError: Task has not finished yet ``` ### Errors[¶](#errors "Link to this heading") If the Task doesn’t succeed, and instead raises an exception, either as part of the Task or as part of running it, the exception and traceback are saved to the [`django.tasks.TaskResult.errors`](../../ref/tasks/#django.tasks.TaskResult.errors "django.tasks.TaskResult.errors") list. Each entry in `errors` is a [`TaskError`](../../ref/tasks/#django.tasks.TaskError "django.tasks.TaskError") containing information about error raised during the execution: ``` >>> result.errors[0].exception_class ``` Note that this is just the type of exception, and contains no other values. The traceback information is reduced to a string which you can use to help debugging: ``` >>> result.errors[0].traceback Traceback (most recent call last): ... TypeError: Object of type datetime is not JSON serializable ``` [**Back to Top](#top) ## Additional Information ### Support Django! * [James Ray donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django’s Tasks framework](#) * [Background Task fundamentals](#background-task-fundamentals) * [Configuring a Task backend](#configuring-a-task-backend) * [Immediate execution](#immediate-execution) * [Dummy backend](#dummy-backend) * [Third-party backends](#third-party-backends) * [Asynchronous support](#asynchronous-support) * [Retrieving backends](#retrieving-backends) * [Defining Tasks](#defining-tasks) * [Task context](#task-context) * [Modifying Tasks](#modifying-tasks) * [Enqueueing Tasks](#enqueueing-tasks) * [Transactions](#transactions) * [Task results](#task-results) * [Updating results](#updating-results) * [Return values](#return-values) * [Errors](#errors) ---- url: https://docs.djangoproject.com/en/6.1/howto/deployment/asgi/hypercorn/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/howto/deployment/asgi/hypercorn/) - [sv](https://docs.djangoproject.com/sv/6.1/howto/deployment/asgi/hypercorn/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/howto/deployment/asgi/hypercorn/) - [pl](https://docs.djangoproject.com/pl/6.1/howto/deployment/asgi/hypercorn/) - [ko](https://docs.djangoproject.com/ko/6.1/howto/deployment/asgi/hypercorn/) - [ja](https://docs.djangoproject.com/ja/6.1/howto/deployment/asgi/hypercorn/) - [it](https://docs.djangoproject.com/it/6.1/howto/deployment/asgi/hypercorn/) - [id](https://docs.djangoproject.com/id/6.1/howto/deployment/asgi/hypercorn/) - [fr](https://docs.djangoproject.com/fr/6.1/howto/deployment/asgi/hypercorn/) - [es](https://docs.djangoproject.com/es/6.1/howto/deployment/asgi/hypercorn/) - [el](https://docs.djangoproject.com/el/6.1/howto/deployment/asgi/hypercorn/) * * [dev](https://docs.djangoproject.com/en/dev/howto/deployment/asgi/hypercorn/) * [6.0](https://docs.djangoproject.com/en/6.0/howto/deployment/asgi/hypercorn/) * [5.2](https://docs.djangoproject.com/en/5.2/howto/deployment/asgi/hypercorn/) * [5.1](https://docs.djangoproject.com/en/5.1/howto/deployment/asgi/hypercorn/) * [5.0](https://docs.djangoproject.com/en/5.0/howto/deployment/asgi/hypercorn/) * [4.2](https://docs.djangoproject.com/en/4.2/howto/deployment/asgi/hypercorn/) * [4.1](https://docs.djangoproject.com/en/4.1/howto/deployment/asgi/hypercorn/) * [4.0](https://docs.djangoproject.com/en/4.0/howto/deployment/asgi/hypercorn/) * [3.2](https://docs.djangoproject.com/en/3.2/howto/deployment/asgi/hypercorn/) * [3.1](https://docs.djangoproject.com/en/3.1/howto/deployment/asgi/hypercorn/) - [**](#top) # How to use Django with Hypercorn[¶](#how-to-use-django-with-hypercorn "Link to this heading") [Hypercorn](https://hypercorn.readthedocs.io/) is an ASGI server that supports HTTP/1, HTTP/2, and HTTP/3 with an emphasis on protocol support. ## Installing Hypercorn[¶](#installing-hypercorn "Link to this heading") You can install Hypercorn with `pip`: ``` python -m pip install hypercorn ``` ## Running Django in Hypercorn[¶](#running-django-in-hypercorn "Link to this heading") When [Hypercorn](https://pypi.org/project/Hypercorn/) is installed, a `hypercorn` command is available which runs ASGI applications. Hypercorn needs to be called with the location of a module containing an ASGI application object, followed by what the application is called (separated by a colon). For a typical Django project, invoking Hypercorn would look like: ``` hypercorn myproject.asgi:application ``` This will start one process listening on `127.0.0.1:8000`. It requires that your project be on the Python path; to ensure that run this command from the same directory as your `manage.py` file. For more advanced usage, please read the [Hypercorn documentation](https://hypercorn.readthedocs.io/). [**Back to Top](#top) ## Additional Information ### Support Django! * [bitcoin casino deutsch donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [How to use Django with Hypercorn](#) * [Installing Hypercorn](#installing-hypercorn) * [Running Django in Hypercorn](#running-django-in-hypercorn) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.2.5/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.2.5/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.2.5/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.2.5/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.2.5/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.2.5/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.2.5/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.2.5/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.2.5/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.2.5/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.2.5/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.2.5/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.2.5/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.2.5/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.2.5/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.2.5/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.2.5/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.2.5/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.2.5/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.2.5/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.2.5/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.2.5/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.2.5/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.2.5/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.2.5/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.2.5/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.2.5/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.2.5/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.2.5/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.2.5/) - [**](#top) # Django 1.2.5 release notes[¶](#django-1-2-5-release-notes "Link to this heading") Welcome to Django 1.2.5! This is the fifth “bugfix” release in the Django 1.2 series, improving the stability and performance of the Django 1.2 codebase. With four exceptions, Django 1.2.5 maintains backwards compatibility with Django 1.2.4. It also contains a number of fixes and other improvements. Django 1.2.5 is a recommended upgrade for any development or deployment currently using or targeting Django 1.2. For full details on the new features, backwards incompatibilities, and deprecated features in the 1.2 branch, see the [Django 1.2 release notes](../1.2/). ### FileField no longer deletes files[¶](#filefield-no-longer-deletes-files "Link to this heading") In earlier Django versions, when a model instance containing a [`FileField`](../../ref/models/fields/#django.db.models.FileField "django.db.models.FileField") was deleted, [`FileField`](../../ref/models/fields/#django.db.models.FileField "django.db.models.FileField") took it upon itself to also delete the file from the backend storage. This opened the door to several potentially serious data-loss scenarios, including rolled-back transactions and fields on different models referencing the same file. In Django 1.2.5, [`FileField`](../../ref/models/fields/#django.db.models.FileField "django.db.models.FileField") will never delete files from the backend storage. If you need cleanup of orphaned files, you’ll need to handle it yourself (for instance, with a custom management command that can be run manually or scheduled to run periodically via e.g. cron). ### Use of custom SQL to load initial data in tests[¶](#use-of-custom-sql-to-load-initial-data-in-tests "Link to this heading") Django provides a custom SQL hooks as a way to inject hand-crafted SQL into the database synchronization process. One of the possible uses for this custom SQL is to insert data into your database. If your custom SQL contains `INSERT` statements, those insertions will be performed every time your database is synchronized. This includes the synchronization of any test databases that are created when you run a test suite. However, in the process of testing the Django 1.3, it was discovered that this feature has never completely worked as advertised. When using database backends that don’t support transactions, or when using a TransactionTestCase, data that has been inserted using custom SQL will not be visible during the testing process. Unfortunately, there was no way to rectify this problem without introducing a backwards incompatibility. Rather than leave SQL-inserted initial data in an uncertain state, Django now enforces the policy that data inserted by custom SQL will *not* be visible during testing. This change only affects the testing process. You can still use custom SQL to load data into your production database as part of the `syncdb` process. If you require data to exist during test conditions, you should either insert it using [test fixtures](../../topics/testing/tools/#topics-testing-fixtures), or using the `setUp()` method of your test case. ### ModelAdmin.lookup\_allowed signature changed[¶](#modeladmin-lookup-allowed-signature-changed "Link to this heading") Django 1.2.4 introduced a method `lookup_allowed` on `ModelAdmin`, to cope with a security issue (changeset [\[15033\]](https://github.com/django/django/commit/85207a245bf09fdebe486b4c7bbcb65300f2a693)). Although this method was never documented, it seems some people have overridden `lookup_allowed`, especially to cope with regressions introduced by that changeset. While the method is still undocumented and not marked as stable, it may be helpful to know that the signature of this function has changed. [**Back to Top](#top) ## Additional Information ### Support Django! * [First Party Software donated to the Django Software Foundation to support Django development. Donate today!](https://www.djangoproject.com/fundraising/) ### Contents * [Django 1.2.5 release notes](#) * [Backwards incompatible changes](#backwards-incompatible-changes) * [CSRF exception for AJAX requests](#csrf-exception-for-ajax-requests) * [FileField no longer deletes files](#filefield-no-longer-deletes-files) * [Use of custom SQL to load initial data in tests](#use-of-custom-sql-to-load-initial-data-in-tests) * [ModelAdmin.lookup\_allowed signature changed](#modeladmin-lookup-allowed-signature-changed) ---- url: https://docs.djangoproject.com/en/6.1/releases/1.7/ ---- [Skip to main content](#main-content) [Documentation](https://docs.djangoproject.com/en/6.1/) * [Getting Help](https://docs.djangoproject.com/en/6.1/faq/help/) - - [zh-hans](https://docs.djangoproject.com/zh-hans/6.1/releases/1.7/) - [sv](https://docs.djangoproject.com/sv/6.1/releases/1.7/) - [pt-br](https://docs.djangoproject.com/pt-br/6.1/releases/1.7/) - [pl](https://docs.djangoproject.com/pl/6.1/releases/1.7/) - [ko](https://docs.djangoproject.com/ko/6.1/releases/1.7/) - [ja](https://docs.djangoproject.com/ja/6.1/releases/1.7/) - [it](https://docs.djangoproject.com/it/6.1/releases/1.7/) - [id](https://docs.djangoproject.com/id/6.1/releases/1.7/) - [fr](https://docs.djangoproject.com/fr/6.1/releases/1.7/) - [es](https://docs.djangoproject.com/es/6.1/releases/1.7/) - [el](https://docs.djangoproject.com/el/6.1/releases/1.7/) * * [dev](https://docs.djangoproject.com/en/dev/releases/1.7/) * [6.0](https://docs.djangoproject.com/en/6.0/releases/1.7/) * [5.2](https://docs.djangoproject.com/en/5.2/releases/1.7/) * [5.1](https://docs.djangoproject.com/en/5.1/releases/1.7/) * [5.0](https://docs.djangoproject.com/en/5.0/releases/1.7/) * [4.2](https://docs.djangoproject.com/en/4.2/releases/1.7/) * [4.1](https://docs.djangoproject.com/en/4.1/releases/1.7/) * [4.0](https://docs.djangoproject.com/en/4.0/releases/1.7/) * [3.2](https://docs.djangoproject.com/en/3.2/releases/1.7/) * [3.1](https://docs.djangoproject.com/en/3.1/releases/1.7/) * [3.0](https://docs.djangoproject.com/en/3.0/releases/1.7/) * [2.2](https://docs.djangoproject.com/en/2.2/releases/1.7/) * [2.1](https://docs.djangoproject.com/en/2.1/releases/1.7/) * [2.0](https://docs.djangoproject.com/en/2.0/releases/1.7/) * [1.11](https://docs.djangoproject.com/en/1.11/releases/1.7/) * [1.10](https://docs.djangoproject.com/en/1.10/releases/1.7/) * [1.9](https://docs.djangoproject.com/en/1.9/releases/1.7/) * [1.8](https://docs.djangoproject.com/en/1.8/releases/1.7/) - [**](#top) # Django 1.7 release notes[¶](#django-1-7-release-notes "Link to this heading") *September 2, 2014* Welcome to Django 1.7! These release notes cover the [new features](#whats-new-1-7), as well as some [backwards incompatible changes](#backwards-incompatible-1-7) you’ll want to be aware of when upgrading from Django 1.6 or older versions. We’ve [begun the deprecation process for some features](#deprecated-features-1-7), and some features have reached the end of their deprecation process and [have been removed](#removed-features-1-7). ## Python compatibility[¶](#python-compatibility "Link to this heading") Django 1.7 requires Python 2.7, 3.2, 3.3, or 3.4. We **highly recommend** and only officially support the latest release of each series. The Django 1.6 series is the last to support Python 2.6. Django 1.7 is the first release to support Python 3.4. This change should affect only a small number of Django users, as most operating-system vendors today are shipping Python 2.7 or newer as their default version. If you’re still using Python 2.6, however, you’ll need to stick to Django 1.6 until you can upgrade your Python version. Per [our support policy](../../internals/release-process/), Django 1.6 will continue to receive security support until the release of Django 1.8. ## What’s new in Django 1.7[¶](#what-s-new-in-django-1-7 "Link to this heading") ### Schema migrations[¶](#schema-migrations "Link to this heading") Django now has built-in support for schema migrations. It allows models to be updated, changed, and deleted by creating migration files that represent the model changes and which can be run on any development, staging or production database. Migrations are covered in [their own documentation](../../topics/migrations/), but a few of the key features are: * `syncdb` has been deprecated and replaced by `migrate`. Don’t worry - calls to `syncdb` will still work as before. * A new `makemigrations` command provides an easy way to autodetect changes to your models and make migrations for them. `django.db.models.signals.pre_syncdb` and `django.db.models.signals.post_syncdb` have been deprecated, to be replaced by [`pre_migrate`](../../ref/signals/#django.db.models.signals.pre_migrate "django.db.models.signals.pre_migrate") and [`post_migrate`](../../ref/signals/#django.db.models.signals.post_migrate "django.db.models.signals.post_migrate") respectively. These new signals have slightly different arguments. Check the documentation for details. * The `allow_syncdb` method on database routers is now called `allow_migrate`, but still performs the same function. Routers with `allow_syncdb` methods will still work, but that method name is deprecated and you should change it as soon as possible (nothing more than renaming is required). * `initial_data` fixtures are no longer loaded for apps with migrations; if you want to load initial data for an app, we suggest you create a migration for your application and define a [`RunPython`](../../ref/migration-operations/#django.db.migrations.operations.RunPython "django.db.migrations.operations.RunPython") or [`RunSQL`](../../ref/migration-operations/#django.db.migrations.operations.RunSQL "django.db.migrations.operations.RunSQL") operation in the `operations` section of the migration. * Test rollback behavior is different for apps with migrations; in particular, Django will no longer emulate rollbacks on non-transactional databases or inside `TransactionTestCase` [unless specifically requested](../../topics/testing/overview/#test-case-serialized-rollback). * It is not advised to have apps without migrations depend on (have a [`ForeignKey`](../../ref/models/fields/#django.db.models.ForeignKey "django.db.models.ForeignKey") or [`ManyToManyField`](../../ref/models/fields/#django.db.models.ManyToManyField "django.db.models.ManyToManyField") to) apps with migrations. ### App-loading refactor[¶](#app-loading-refactor "Link to this heading") Historically, Django applications were tightly linked to models. A singleton known as the “app cache” dealt with both installed applications and models. The models module was used as an identifier for applications in many APIs. As the concept of [Django applications](../../ref/applications/) matured, this code showed some shortcomings. It has been refactored into an “app registry” where models modules no longer have a central role and where it’s possible to attach configuration data to applications. Improvements thus far include: * Applications can run code at startup, before Django does anything else, with the [`ready()`](../../ref/applications/#django.apps.AppConfig.ready "django.apps.AppConfig.ready") method of their configuration. * Application labels are assigned correctly to models even when they’re defined outside of `models.py`. You don’t have to set [`app_label`](../../ref/models/options/#django.db.models.Options.app_label "django.db.models.Options.app_label") explicitly any more. * It is possible to omit `models.py` entirely if an application doesn’t have any models. * Applications can be relabeled with the [`label`](../../ref/applications/#django.apps.AppConfig.label "django.apps.AppConfig.label") attribute of application configurations, to work around label conflicts. * The name of applications can be customized in the admin with the [`verbose_name`](../../ref/applications/#django.apps.AppConfig.verbose_name "django.apps.AppConfig.verbose_name") of application configurations. * The admin automatically calls [`autodiscover()`](../../ref/contrib/admin/#django.contrib.admin.autodiscover "django.contrib.admin.autodiscover") when Django starts. You can consequently remove this line from your URLconf. * Django imports all application configurations and models as soon as it starts, through a deterministic and straightforward process. This should make it easier to diagnose import issues such as import loops. ### New method on Field subclasses[¶](#new-method-on-field-subclasses "Link to this heading") To help power both schema migrations and to enable easier addition of composite keys in future releases of Django, the [`Field`](../../ref/models/fields/#django.db.models.Field "django.db.models.Field") API now has a new required method: `deconstruct()`. This method takes no arguments, and returns a tuple of four items: * `name`: The field’s attribute name on its parent model, or `None` if it is not part of a model * `path`: A dotted, Python path to the class of this field, including the class name. * `args`: Positional arguments, as a list * `kwargs`: Keyword arguments, as a dict These four values allow any field to be serialized into a file, as well as allowing the field to be copied safely, both essential parts of these new features. This change should not affect you unless you write custom Field subclasses; if you do, you may need to reimplement the `deconstruct()` method if your subclass changes the method signature of `__init__` in any way. If your field just inherits from a built-in Django field and doesn’t override `__init__`, no changes are necessary. If you do need to override `deconstruct()`, a good place to start is the built-in Django fields (`django/db/models/fields/__init__.py`) as several fields, including `DecimalField` and `DateField`, override it and show how to call the method on the superclass and simply add or remove extra arguments. This also means that all arguments to fields must themselves be serializable; to see what we consider serializable, and to find out how to make your own classes serializable, read the [migration serialization documentation](../../topics/migrations/#migration-serializing). ### Calling custom `QuerySet` methods from the `Manager`[¶](#calling-custom-queryset-methods-from-the-manager "Link to this heading") Historically, the recommended way to make reusable model queries was to create methods on a custom `Manager` class. The problem with this approach was that after the first method call, you’d get back a `QuerySet` instance and couldn’t call additional custom manager methods. Though not documented, it was common to work around this issue by creating a custom `QuerySet` so that custom methods could be chained; but the solution had a number of drawbacks: * The custom `QuerySet` and its custom methods were lost after the first call to `values()` or `values_list()`. * Writing a custom `Manager` was still necessary to return the custom `QuerySet` class and all methods that were desired on the `Manager` had to be proxied to the `QuerySet`. The whole process went against the DRY principle. The [`QuerySet.as_manager()`](../../ref/models/querysets/#django.db.models.query.QuerySet.as_manager "django.db.models.query.QuerySet.as_manager") class method can now directly [create Manager with QuerySet methods](../../topics/db/managers/#create-manager-with-queryset-methods): ``` class FoodQuerySet(models.QuerySet): def pizzas(self): return self.filter(kind="pizza") def vegetarian(self): return self.filter(vegetarian=True) class Food(models.Model): kind = models.CharField(max_length=50) vegetarian = models.BooleanField(default=False) objects = FoodQuerySet.as_manager() Food.objects.pizzas().vegetarian() ``` ### Using a custom manager when traversing reverse relations[¶](#using-a-custom-manager-when-traversing-reverse-relations "Link to this heading") It is now possible to [specify a custom manager](../../topics/db/queries/#using-custom-reverse-manager) when traversing a reverse relationship: ``` class Blog(models.Model): pass class Entry(models.Model): blog = models.ForeignKey(Blog) objects = models.Manager() # Default Manager entries = EntryManager() # Custom Manager b = Blog.objects.get(id=1) b.entry_set(manager="entries").all() ``` ### New system check framework[¶](#new-system-check-framework "Link to this heading") We’ve added a new [System check framework](../../ref/checks/) for detecting common problems (like invalid models) and providing hints for resolving those problems. The framework is extensible so you can add your own checks for your own apps and libraries. To perform system checks, you use the [`check`](../../ref/django-admin/#django-admin-check) management command. This command replaces the older `validate` management command. ### New `Prefetch` object for advanced `prefetch_related` operations.[¶](#new-prefetch-object-for-advanced-prefetch-related-operations "Link to this heading") The new [`Prefetch`](../../ref/models/querysets/#django.db.models.Prefetch "django.db.models.Prefetch") object allows customizing prefetch operations. You can specify the `QuerySet` used to traverse a given relation or customize the storage location of prefetch results. This enables things like filtering prefetched relations, calling [`select_related()`](../../ref/models/querysets/#django.db.models.query.QuerySet.select_related "django.db.models.query.QuerySet.select_related") from a prefetched relation, or prefetching the same relation multiple times with different querysets. See [`prefetch_related()`](../../ref/models/querysets/#django.db.models.query.QuerySet.prefetch_related "django.db.models.query.QuerySet.prefetch_related") for more details. ### Admin shortcuts support time zones[¶](#admin-shortcuts-support-time-zones "Link to this heading") The “today” and “now” shortcuts next to date and time input widgets in the admin are now operating in the [current time zone](../../topics/i18n/timezones/#default-current-time-zone). Previously, they used the browser time zone, which could result in saving the wrong value when it didn’t match the current time zone on the server. In addition, the widgets now display a help message when the browser and server time zone are different, to clarify how the value inserted in the field will be interpreted. ### Using database cursors as context managers[¶](#using-database-cursors-as-context-managers "Link to this heading") Prior to Python 2.7, database cursors could be used as a context manager. The specific backend’s cursor defined the behavior of the context manager. The behavior of magic method lookups was changed with Python 2.7 and cursors were no longer usable as context managers. Django 1.7 allows a cursor to be used as a context manager. That is, the following can be used: ``` with connection.cursor() as c: c.execute(...) ``` instead of: ``` c = connection.cursor() try: c.execute(...) finally: c.close() ``` ### Custom lookups[¶](#custom-lookups "Link to this heading") It is now possible to write custom lookups and transforms for the ORM. Custom lookups work just like Django’s built-in lookups (e.g. `lte`, `icontains`) while transforms are a new concept. The [`django.db.models.Lookup`](../../ref/models/lookups/#django.db.models.Lookup "django.db.models.Lookup") class provides a way to add lookup operators for model fields. As an example it is possible to add `day_lte` operator for `DateFields`. The [`django.db.models.Transform`](../../ref/models/lookups/#django.db.models.Transform "django.db.models.Transform") class allows transformations of database values prior to the final lookup. For example it is possible to write a `year` transform that extracts year from the field’s value. Transforms allow for chaining. After the `year` transform has been added to `DateField` it is possible to filter on the transformed value, for example `qs.filter(author__birthdate__year__lte=1981)`. For more information about both custom lookups and transforms refer to the [custom lookups](../../howto/custom-lookups/) documentation. ### Improvements to `Form` error handling[¶](#improvements-to-form-error-handling "Link to this heading") #### `Form.add_error()`[¶](#form-add-error "Link to this heading") Previously there were two main patterns for handling errors in forms: * Raising a [`ValidationError`](../../ref/exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") from within certain functions (e.g. `Field.clean()`, `Form.clean_()`, or `Form.clean()` for non-field errors.) * Fiddling with `Form._errors` when targeting a specific field in `Form.clean()` or adding errors from outside of a “clean” method (e.g. directly from a view). Using the former pattern was straightforward since the form can guess from the context (i.e. which method raised the exception) where the errors belong and automatically process them. This remains the canonical way of adding errors when possible. However the latter was fiddly and error-prone, since the burden of handling edge cases fell on the user. The new [`add_error()`](../../ref/forms/api/#django.forms.Form.add_error "django.forms.Form.add_error") method allows adding errors to specific form fields from anywhere without having to worry about the details such as creating instances of `django.forms.utils.ErrorList` or dealing with `Form.cleaned_data`. This new API replaces manipulating `Form._errors` which now becomes a private API. See [Cleaning and validating fields that depend on each other](../../ref/forms/validation/#validating-fields-with-clean) for an example using `Form.add_error()`. #### Error metadata[¶](#error-metadata "Link to this heading") The [`ValidationError`](../../ref/exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError") constructor accepts metadata such as error `code` or `params` which are then available for interpolating into the error message (see [Raising ValidationError](../../ref/forms/validation/#raising-validation-error) for more details); however, before Django 1.7 those metadata were discarded as soon as the errors were added to [`Form.errors`](../../ref/forms/api/#django.forms.Form.errors "django.forms.Form.errors"). [`Form.errors`](../../ref/forms/api/#django.forms.Form.errors "django.forms.Form.errors") and `django.forms.utils.ErrorList` now store the `ValidationError` instances so these metadata can be retrieved at any time through the new [`Form.errors.as_data`](../../ref/forms/api/#django.forms.Form.errors.as_data "django.forms.Form.errors.as_data") method. The retrieved `ValidationError` instances can then be identified thanks to their error `code` which enables things like rewriting the error’s message or writing custom logic in a view when a given error is present. It can also be used to serialize the errors in a custom format such as XML. The new [`Form.errors.as_json()`](../../ref/forms/api/#django.forms.Form.errors.as_json "django.forms.Form.errors.as_json") method is a convenience method which returns error messages along with error codes serialized as JSON. `as_json()` uses `as_data()` and gives an idea of how the new system could be extended. #### Error containers and backward compatibility[¶](#error-containers-and-backward-compatibility "Link to this heading") Heavy changes to the various error containers were necessary in order to support the features above, specifically [`Form.errors`](../../ref/forms/api/#django.forms.Form.errors "django.forms.Form.errors"), `django.forms.utils.ErrorList`, and the internal storages of [`ValidationError`](../../ref/exceptions/#django.core.exceptions.ValidationError "django.core.exceptions.ValidationError"). These containers which used to store error strings now store `ValidationError` instances and public APIs have been adapted to make this as transparent as possible, but if you’ve been using private APIs, some of the changes are backwards incompatible; see [ValidationError constructor and internal storage](#validation-error-constructor-and-internal-storage) for more details. ### Minor features[¶](#minor-features "Link to this heading") #### [`django.contrib.admin`](../../ref/contrib/admin/#module-django.contrib.admin "django.contrib.admin: Django's admin site.")[¶](#django-contrib-admin "Link to this heading") * You can now implement [`site_header`](../../ref/contrib/admin/#django.contrib.admin.AdminSite.site_header "django.contrib.admin.AdminSite.site_header"), [`site_title`](../../ref/contrib/admin/#django.contrib.admin.AdminSite.site_title "django.contrib.admin.AdminSite.site_title"), and [`index_title`](../../ref/contrib/admin/#django.contrib.admin.AdminSite.index_title "django.contrib.admin.AdminSite.index_title") attributes on a custom [`AdminSite`](../../ref/contrib/admin/#django.contrib.admin.AdminSite "django.contrib.admin.AdminSite") in order to easily change the admin site’s page title and header text. No more needing to override templates! * Buttons in [`django.contrib.admin`](../../ref/contrib/admin/#module-django.contrib.admin "django.contrib.admin: Django's admin site.") now use the `border-radius` CSS property for rounded corners rather than GIF background images. * Some admin templates now have `app-` and `model-` classes in their `` tag to allow customizing the CSS per app or per model. * The admin changelist cells now have a `field-` class in the HTML to enable style customizations. * The admin’s search fields can now be customized per-request thanks to the new [`django.contrib.admin.ModelAdmin.get_search_fields()`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.get_search_fields "django.contrib.admin.ModelAdmin.get_search_fields") method. * The [`ModelAdmin.get_fields()`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.get_fields "django.contrib.admin.ModelAdmin.get_fields") method may be overridden to customize the value of [`ModelAdmin.fields`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.fields "django.contrib.admin.ModelAdmin.fields"). * In addition to the existing `admin.site.register` syntax, you can use the new [`register()`](../../ref/contrib/admin/#django.contrib.admin.register "django.contrib.admin.register") decorator to register a [`ModelAdmin`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin "django.contrib.admin.ModelAdmin"). * You may specify [`ModelAdmin.list_display_links`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.list_display_links "django.contrib.admin.ModelAdmin.list_display_links") `= None` to disable links on the change list page grid. * You may now specify [`ModelAdmin.view_on_site`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.view_on_site "django.contrib.admin.ModelAdmin.view_on_site") to control whether or not to display the “View on site” link. * You can specify a descending ordering for a [`ModelAdmin.list_display`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.list_display "django.contrib.admin.ModelAdmin.list_display") value by prefixing the `admin_order_field` value with a hyphen. * The [`ModelAdmin.get_changeform_initial_data()`](../../ref/contrib/admin/#django.contrib.admin.ModelAdmin.get_changeform_initial_data "django.contrib.admin.ModelAdmin.get_changeform_initial_data") method may be overridden to define custom behavior for setting initial change form data. #### [`django.contrib.auth`](../../topics/auth/#module-django.contrib.auth "django.contrib.auth: Django's authentication framework.")[¶](#django-contrib-auth "Link to this heading") * Any `**kwargs` passed to [`email_user()`](../../ref/contrib/auth/#django.contrib.auth.models.User.email_user "django.contrib.auth.models.User.email_user") are passed to the underlying [`send_mail()`](../../topics/email/#django.core.mail.send_mail "django.core.mail.send_mail") call. * The [`permission_required()`](../../topics/auth/default/#django.contrib.auth.decorators.permission_required "django.contrib.auth.decorators.permission_required") decorator can take a list of permissions as well as a single permission. * You can override the new [`AuthenticationForm.confirm_login_allowed()`](../../topics/auth/default/#django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed "django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed") method to more easily customize the login policy. * `django.contrib.auth.views.password_reset()` takes an optional `html_email_template_name` parameter used to send a multipart HTML email for password resets. * The [`AbstractBaseUser.get_session_auth_hash()`](../../topics/auth/customizing/#django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash "django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash") method was added and if your [`AUTH_USER_MODEL`](../../ref/settings/#std-setting-AUTH_USER_MODEL) inherits from [`AbstractBaseUser`](../../topics/auth/customizing/#django.contrib.auth.models.AbstractBaseUser "django.contrib.auth.models.AbstractBaseUser"), changing a user’s password now invalidates old sessions if the `django.contrib.auth.middleware.SessionAuthenticationMiddleware` is enabled. See [Session invalidation on password change](../../topics/auth/default/#session-invalidation-on-password-change) for more details. #### `django.contrib.formtools`[¶](#django-contrib-formtools "Link to this heading") * Calls to `WizardView.done()` now include a `form_dict` to allow easier access to forms by their step name. #### [`django.contrib.gis`](../../ref/contrib/gis/#module-django.contrib.gis "django.contrib.gis: Geographic Information System (GIS) extensions for Django")[¶](#django-contrib-gis "Link to this heading") * The default OpenLayers library version included in widgets has been updated from 2.11 to 2.13. * Prepared geometries now also support the `crosses`, `disjoint`, `overlaps`, `touches` and `within` predicates, if GEOS 3.3 or later is installed. #### [`django.contrib.messages`](../../ref/contrib/messages/#module-django.contrib.messages "django.contrib.messages: Provides cookie- and session-based temporary message storage.")[¶](#django-contrib-messages "Link to this heading") * The backends for [`django.contrib.messages`](../../ref/contrib/messages/#module-django.contrib.messages "django.contrib.messages: Provides cookie- and session-based temporary message storage.") that use cookies, will now follow the [`SESSION_COOKIE_SECURE`](../../ref/settings/#std-setting-SESSION_COOKIE_SECURE) and [`SESSION_COOKIE_HTTPONLY`](../../ref/settings/#std-setting-SESSION_COOKIE_HTTPONLY) settings. * The [messages context processor](../../ref/contrib/messages/#message-displaying) now adds a dictionary of default levels under the name `DEFAULT_MESSAGE_LEVELS`. * [`Message`](../../ref/contrib/messages/#django.contrib.messages.Message "django.contrib.messages.Message") objects now have a `level_tag` attribute that contains the string representation of the message level. #### [`django.contrib.redirects`](../../ref/contrib/redirects/#module-django.contrib.redirects "django.contrib.redirects: A framework for managing redirects.")[¶](#django-contrib-redirects "Link to this heading") * [`RedirectFallbackMiddleware`](../../ref/contrib/redirects/#django.contrib.redirects.middleware.RedirectFallbackMiddleware "django.contrib.redirects.middleware.RedirectFallbackMiddleware") has two new attributes ([`response_gone_class`](../../ref/contrib/redirects/#django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_gone_class "django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_gone_class") and [`response_redirect_class`](../../ref/contrib/redirects/#django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_redirect_class "django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_redirect_class")) that specify the types of [`HttpResponse`](../../ref/request-response/#django.http.HttpResponse "django.http.HttpResponse") instances the middleware returns. #### [`django.contrib.sessions`](../../topics/http/sessions/#module-django.contrib.sessions "django.contrib.sessions: Provides session management for Django projects.")[¶](#django-contrib-sessions "Link to this heading") * The `"django.contrib.sessions.backends.cached_db"` session backend now respects [`SESSION_CACHE_ALIAS`](../../ref/settings/#std-setting-SESSION_CACHE_ALIAS). In previous versions, it always used the `default` cache. #### [`django.contrib.sitemaps`](../../ref/contrib/sitemaps/#module-django.contrib.sitemaps "django.contrib.sitemaps: A framework for generating Google sitemap XML files.")[¶](#django-contrib-sitemaps "Link to this heading") * The [`sitemap framework`](../../ref/contrib/sitemaps/#module-django.contrib.sitemaps "django.contrib.sitemaps: A framework for generating Google sitemap XML files.") now makes use of [`lastmod`](../../ref/contrib/sitemaps/#django.contrib.sitemaps.Sitemap.lastmod "django.contrib.sitemaps.Sitemap.lastmod") to set a `Last-Modified` header in the response. This makes it possible for the [`ConditionalGetMiddleware`](../../ref/middleware/#django.middleware.http.ConditionalGetMiddleware "django.middleware.http.ConditionalGetMiddleware") to handle conditional `GET` requests for sitemaps which set `lastmod`. #### [`django.contrib.sites`](../../ref/contrib/sites/#module-django.contrib.sites "django.contrib.sites: Lets you operate multiple websites from the same database and Django project")[¶](#django-contrib-sites "Link to this heading") * The new [`django.contrib.sites.middleware.CurrentSiteMiddleware`](../../ref/middleware/#django.contrib.sites.middleware.CurrentSiteMiddleware "django.contrib.sites.middleware.CurrentSiteMiddleware") allows setting the current site on each request. #### [`django.contrib.staticfiles`](../../ref/contrib/staticfiles/#module-django.contrib.staticfiles "django.contrib.staticfiles: An app for handling static files.")[¶](#django-contrib-staticfiles "Link to this heading") * The [static files storage classes](../../ref/contrib/staticfiles/#staticfiles-storages) may be subclassed to override the permissions that collected static files and directories receive by setting the [`file_permissions_mode`](../../ref/files/storage/#django.core.files.storage.FileSystemStorage.file_permissions_mode "django.core.files.storage.FileSystemStorage.file_permissions_mode") and [`directory_permissions_mode`](../../ref/files/storage/#django.core.files.storage.FileSystemStorage.directory_permissions_mode "django.core.files.storage.FileSystemStorage.directory_permissions_mode") parameters. See [`collectstatic`](../../ref/contrib/staticfiles/#django-admin-collectstatic) for example usage. * The `CachedStaticFilesStorage` backend gets a sibling class called [`ManifestStaticFilesStorage`](../../ref/contrib/staticfiles/#django.contrib.staticfiles.storage.ManifestStaticFilesStorage "django.contrib.staticfiles.storage.ManifestStaticFilesStorage") that doesn’t use the cache system at all but instead a JSON file called `staticfiles.json` for storing the mapping between the original file name (e.g. `css/styles.css`) and the hashed file name (e.g. `css/styles.55e7cbb9ba48.css`). The `staticfiles.json` file is created when running the [`collectstatic`](../../ref/contrib/staticfiles/#django-admin-collectstatic) management command and should be a less expensive alternative for remote storages such as Amazon S3. See the [`ManifestStaticFilesStorage`](../../ref/contrib/staticfiles/#django.contrib.staticfiles.storage.ManifestStaticFilesStorage "django.contrib.staticfiles.storage.ManifestStaticFilesStorage") docs for more information. * [`findstatic`](../../ref/contrib/staticfiles/#django-admin-findstatic) now accepts verbosity flag level 2, meaning it will show the relative paths of the directories it searched. See [`findstatic`](../../ref/contrib/staticfiles/#django-admin-findstatic) for example output. #### [`django.contrib.syndication`](../../ref/contrib/syndication/#module-django.contrib.syndication "django.contrib.syndication: A framework for generating syndication feeds, in RSS and Atom, quite easily.")[¶](#django-contrib-syndication "Link to this heading") * The [`Atom1Feed`](../../ref/utils/#django.utils.feedgenerator.Atom1Feed "django.utils.feedgenerator.Atom1Feed") syndication feed’s `updated` element now utilizes `updateddate` instead of `pubdate`, allowing the `published` element to be included in the feed (which relies on `pubdate`). #### Cache[¶](#cache "Link to this heading") * Access to caches configured in [`CACHES`](../../ref/settings/#std-setting-CACHES) is now available via [`django.core.cache.caches`](../../topics/cache/#django.core.cache.caches "django.core.cache.caches"). This dict-like object provides a different instance per thread. It supersedes `django.core.cache.get_cache()` which is now deprecated. * If you instantiate cache backends directly, be aware that they aren’t thread-safe any more, as [`django.core.cache.caches`](../../topics/cache/#django.core.cache.caches "django.core.cache.caches") now yields different instances per thread. * Defining the [`TIMEOUT`](../../ref/settings/#std-setting-CACHES-TIMEOUT) argument of the [`CACHES`](../../ref/settings/#std-setting-CACHES) setting as `None` will set the cache keys as “non-expiring” by default. Previously, it was only possible to pass `timeout=None` to the cache backend’s `set()` method. #### Cross Site Request Forgery[¶](#cross-site-request-forgery "Link to this heading") * The [`CSRF_COOKIE_AGE`](../../ref/settings/#std-setting-CSRF_COOKIE_AGE) setting facilitates the use of session-based CSRF cookies. #### Email[¶](#email "Link to this heading") * [`send_mail()`](../../topics/email/#django.core.mail.send_mail "django.core.mail.send_mail") now accepts an `html_message` parameter for sending a multipart *text/plain* and *text/html* email. * The [SMTP EmailBackend](../../topics/email/#topic-email-smtp-backend) now accepts a `timeout` parameter. #### File Storage[¶](#file-storage "Link to this heading") * File locking on Windows previously depended on the PyWin32 package; if it wasn’t installed, file locking failed silently. That dependency has been removed, and file locking is now implemented natively on both Windows and Unix. #### File Uploads[¶](#file-uploads "Link to this heading") * The new [`UploadedFile.content_type_extra`](../../ref/files/uploads/#django.core.files.uploadedfile.UploadedFile.content_type_extra "django.core.files.uploadedfile.UploadedFile.content_type_extra") attribute contains extra parameters passed to the `content-type` header on a file upload. * The new [`FILE_UPLOAD_DIRECTORY_PERMISSIONS`](../../ref/settings/#std-setting-FILE_UPLOAD_DIRECTORY_PERMISSIONS) setting controls the file system permissions of directories created during file upload, like [`FILE_UPLOAD_PERMISSIONS`](../../ref/settings/#std-setting-FILE_UPLOAD_PERMISSIONS) does for the files themselves. * The [`FileField.upload_to`](../../ref/models/fields/#django.db.models.FileField.upload_to "django.db.models.FileField.upload_to") attribute is now optional. If it is omitted or given `None` or an empty string, a subdirectory won’t be used for storing the uploaded files. * Uploaded files are now explicitly closed before the response is delivered to the client. Partially uploaded files are also closed as long as they are named `file` in the upload handler. * [`Storage.get_available_name()`](../../ref/files/storage/#django.core.files.storage.Storage.get_available_name "django.core.files.storage.Storage.get_available_name") now appends an underscore plus a random 7 character alphanumeric string (e.g. `"_x3a1gho"`), rather than iterating through an underscore followed by a number (e.g. `"_1"`, `"_2"`, etc.) to prevent a denial-of-service attack. This change was also made in the 1.6.6, 1.5.9, and 1.4.14 security releases. #### Forms[¶](#forms "Link to this heading") * The `