Getting Started

Django-filter provides a simple way to filter down a queryset based on parameters a user provides. Say we have a Product model and we want to let our users filter which products they see on a list page.

Note

If you’re using django-filter with Django Rest Framework, it’s recommended that you read the integration docs after this guide.

The model

Let’s start with our model:

from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=255)
    price = models.DecimalField()
    description = models.TextField()
    release_date = models.DateField()
    manufacturer = models.ForeignKey(Manufacturer)

The filter

We have a number of fields and we want to let our users filter based on the name, the price or the release_date. We create a FilterSet for this:

import django_filters

class ProductFilter(django_filters.FilterSet):
    name = django_filters.CharFilter(lookup_expr='iexact')

    class Meta:
        model = Product
        fields = ['price', 'release_date']

As you can see this uses a very similar API to Django’s ModelForm. Just like with a ModelForm we can also override filters, or add new ones using a declarative syntax.

Declaring filters

The declarative syntax provides you with the most flexibility when creating filters, however it is fairly verbose. We’ll use the below example to outline the core filter arguments on a FilterSet:

class ProductFilter(django_filters.FilterSet):
    price = django_filters.NumberFilter()
    price__gt = django_filters.NumberFilter(field_name='price', lookup_expr='gt')
    price__lt = django_filters.NumberFilter(field_name='price', lookup_expr='lt')

    release_year = django_filters.NumberFilter(field_name='release_date', lookup_expr='year')
    release_year__gt = django_filters.NumberFilter(field_name='release_date', lookup_expr='year__gt')
    release_year__lt = django_filters.NumberFilter(field_name='release_date', lookup_expr='year__lt')

    manufacturer__name = django_filters.CharFilter(lookup_expr='icontains')

    class Meta:
        model = Product

There are two main arguments for filters:

• field_name: The name of the model field to filter on. You can traverse “relationship paths” using Django’s __ syntax to filter fields on a related model. ex, manufacturer__name.

• lookup_expr: The field lookup to use when filtering. Django’s __ syntax can again be used in order to support lookup transforms. ex, year__gte.

Together, the field field_name and lookup_expr represent a complete Django lookup expression. A detailed explanation of lookup expressions is provided in Django’s lookup reference. django-filter supports expressions containing both transforms and a final lookup.

Generating filters with Meta.fields

The FilterSet Meta class provides a fields attribute that can be used for easily specifying multiple filters without significant code duplication. The base syntax supports a list of multiple field names:

import django_filters

class ProductFilter(django_filters.FilterSet):
    class Meta:
        model = Product
        fields = ['price', 'release_date']

The above generates ‘exact’ lookups for both the ‘price’ and ‘release_date’ fields.

Additionally, a dictionary can be used to specify multiple lookup expressions for each field:

import django_filters

class ProductFilter(django_filters.FilterSet):
    class Meta:
        model = Product
        fields = {
            'price': ['lt', 'gt'],
            'release_date': ['exact', 'year__gt'],
        }

The above would generate ‘price__lt’, ‘price__gt’, ‘release_date’, and ‘release_date__year__gt’ filters.

Note

The filter lookup type ‘exact’ is an implicit default and therefore never added to a filter name. In the above example, the release date’s exact filter is ‘release_date’, not ‘release_date__exact’.

Items in the fields sequence in the Meta class may include “relationship paths” using Django’s __ syntax to filter on fields on a related model:

class ProductFilter(django_filters.FilterSet):
    class Meta:
        model = Product
        fields = ['manufacturer__country']

Overriding default filters

Like django.contrib.admin.ModelAdmin, it is possible to override default filters for all the models fields of the same kind using filter_overrides on the Meta class:

class ProductFilter(django_filters.FilterSet):

    class Meta:
        model = Product
        fields = {
            'name': ['exact'],
            'release_date': ['isnull'],
        }
        filter_overrides = {
            models.CharField: {
                'filter_class': django_filters.CharFilter,
                'extra': lambda f: {
                    'lookup_expr': 'icontains',
                },
            },
            models.BooleanField: {
                'filter_class': django_filters.BooleanFilter,
                'extra': lambda f: {
                    'widget': forms.CheckboxInput,
                },
            },
        }

Process filters together with Meta.groups

Filters can be added to a group, allowing them to be processed together. This overrides their validation and filtering behavior. In the example below, first_name and last_name are mutually required. Filtering by one of the params requires that both are provided. For more information, see the group reference.

class UserFilter(django_filters.FilterSet):
    class Meta:
        model = User
        fields = ['username', 'first_name', 'last_name']
        groups = [
            RequiredGroup(['first_name', 'last_name']),
        ]

Request-based filtering

The FilterSet may be initialized with an optional request argument. If a request object is passed, then you may access the request during filtering. This allows you to filter by properties on the request, such as the currently logged-in user or the Accepts-Languages header.

Note

It is not guaranteed that a request will be provied to the FilterSet instance. Any code depending on a request should handle the None case.

Filtering the primary .qs

To filter the primary queryset by the request object, simply override the FilterSet.qs property. For example, you could filter blog articles to only those that are published and those that are owned by the logged-in user (presumably the author’s draft articles).

class ArticleFilter(django_filters.FilterSet):

    class Meta:
        model = Article
        fields = [...]

    @property
    def qs(self):
        parent = super(ArticleFilter, self).qs
        author = getattr(self.request, 'user', None)

        return parent.filter(is_published=True) \
            | parent.filter(author=author)

Filtering the related queryset for ModelChoiceFilter

The queryset argument for ModelChoiceFilter and ModelMultipleChoiceFilter supports callable behavior. If a callable is passed, it will be invoked with the request as its only argument. This allows you to perform the same kinds of request-based filtering without resorting to overriding FilterSet.__init__.

def departments(request):
    if request is None:
        return Department.objects.none()

    company = request.user.company
    return company.department_set.all()

class EmployeeFilter(filters.FilterSet):
    department = filters.ModelChoiceFilter(queryset=departments)
    ...

Customize filtering with Filter.method

You can control the behavior of a filter by specifying a method to perform filtering. View more information in the method reference. Note that you may access the filterset’s properties, such as the request.

class F(django_filters.FilterSet):
    username = CharFilter(method='my_custom_filter')

    class Meta:
        model = User
        fields = ['username']

    def my_custom_filter(self, queryset, name, value):
        return queryset.filter(**{
            name: value,
        })

The view

Now we need to write a view:

def product_list(request):
    f = ProductFilter(request.GET, queryset=Product.objects.all())
    return render(request, 'my_app/template.html', {'filter': f})

If a queryset argument isn’t provided then all the items in the default manager of the model will be used.

If you want to access the filtered objects in your views, for example if you want to paginate them, you can do that. They are in f.qs

The URL conf

We need a URL pattern to call the view:

url(r'^list$', views.product_list)

The template

And lastly we need a template:

{% extends "base.html" %}

{% block content %}
    <form action="" method="get">
        {{ filter.form.as_p }}
        <input type="submit" />
    </form>
    {% for obj in filter.qs %}
        {{ obj.name }} - ${{ obj.price }}<br />
    {% endfor %}
{% endblock %}

And that’s all there is to it! The form attribute contains a normal Django form, and when we iterate over the FilterSet.qs we get the objects in the resulting queryset.

Generic view & configuration

In addition to the above usage there is also a class-based generic view included in django-filter, which lives at django_filters.views.FilterView. You must provide either a model or filterset_class argument, similar to ListView in Django itself:

# urls.py
from django.conf.urls import url
from django_filters.views import FilterView
from myapp.models import Product

urlpatterns = [
    url(r'^list/$', FilterView.as_view(model=Product)),
]

If you provide a model optionally you can set filterset_fields to specify a list or a tuple of the fields that you want to include for the automatic construction of the filterset class.

You must provide a template at <app>/<model>_filter.html which gets the context parameter filter. Additionally, the context will contain object_list which holds the filtered queryset.

A legacy functional generic view is still included in django-filter, although its use is deprecated. It can be found at django_filters.views.object_filter. You must provide the same arguments to it as the class based view:

# urls.py
from django.conf.urls import url
from django_filters.views import object_filter
from myapp.models import Product

urlpatterns = [
    url(r'^list/$', object_filter, {'model': Product}),
]

The needed template and its context variables will also be the same as the class-based view above.