How to Install django-filter in Python

django-filter is a reusable Django application for adding dynamic filtering to QuerySets. It lets users filter data through URL parameters without writing custom query logic.

Installing it takes only a few minutes. This guide walks through the full setup, from pip install to your first FilterSet and Django REST Framework integration.

You will also learn how to troubleshoot the most common installation errors that beginners run into.

What Is django-filter?

django-filter generates filtering interfaces that look and behave like the Django admin's list filters. Its API closely mirrors Django's ModelForms, so it feels familiar from the start.

You define a FilterSet class. You list the model fields you want to expose. django-filter handles the query building and validation for you.

The package supports plain Django views and Django REST Framework. It is mature, stable, and actively maintained with a calendar-based versioning scheme[reference:0].

If you plan to build scalable APIs, django-filter is often the first filtering tool developers reach for. For a broader look at API design, you can explore Django Rest Framework best practices for scalable APIs alongside this setup.

Prerequisites

Before you install django-filter, make sure your environment is ready.

• Python 3.10 or newer installed on your machine
• A current Django version in your project
• pip available for package installation
• An active virtual environment is strongly recommended

django-filter requires a current version of Django and is tested against all supported Python versions[reference:1]. It also works with the latest Django REST Framework.

Activate your virtual environment before installing. This keeps django-filter isolated from other projects on your system.

Installing django-filter with pip

The simplest installation method is pip. Run this command inside your activated virtual environment.

 pip install django-filter 

This downloads the latest stable release from PyPI. The package has no heavy dependencies, so installation is fast.

If you use a requirements file, add django-filter with a pinned version for reproducible builds.

 pip install django-filter==25.2 

Pinning a version prevents surprise upgrades during deployment. You can check the current version on the PyPI page.

Adding django_filters to INSTALLED_APPS

After installation, you must register the app. Open your Django project's settings.py file and add 'django_filters' to the INSTALLED_APPS list[reference:2].

 # settings.py INSTALLED_APPS = [ 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', # Third-party apps 'django_filters', # Your apps 'myapp', ] 

Skipping this step is the most common mistake. Without it, Django will not recognize the filter templates and form widgets.

The app name in INSTALLED_APPS uses an underscore: django_filters. The pip package name uses a hyphen: django-filter. Both are correct in their respective contexts.

Verifying the Installation

To confirm everything is wired up, run a quick check from the command line. Django has a built-in system check command.

 python manage.py check 

If django-filter is installed and registered correctly, you will see a clean output.

 System check identified no issues (0 silenced). 

You can also import the package directly in a Python shell to verify it is on your path.

 # In a Django shell or any Python script import django_filters print(django_filters.__version__) 

The output shows the installed version, confirming the package is importable.

 25.2 

Your First FilterSet

A FilterSet class defines which fields users can filter on. It is the core building block of django-filter.

Imagine you have a Product model with fields for name, price, and manufacturer. Here is a FilterSet for it[reference:3].

 # filters.py import django_filters from .models import Product class ProductFilter(django_filters.FilterSet): """Filter products by name, price, and manufacturer.""" class Meta: model = Product fields = ['name', 'price', 'manufacturer'] 

The Meta class tells django-filter which model to use and which fields to expose. Only those fields become filterable through query parameters.

You can also specify lookup expressions for more precise control. For example, filtering prices by range instead of exact match.

 class ProductFilter(django_filters.FilterSet): min_price = django_filters.NumberFilter( field_name="price", lookup_expr='gte' ) max_price = django_filters.NumberFilter( field_name="price", lookup_expr='lte' ) class Meta: model = Product fields = ['category', 'in_stock'] 

The NumberFilter class creates a numeric input. The lookup_expr option sets greater-than-or-equal or less-than-or-equal comparisons.

Using a dedicated filters.py file keeps your filter logic separate from views. This makes the codebase easier to navigate as it grows.

Using the FilterSet in a View

Now pass the FilterSet into your view and apply it to the queryset[reference:4].

 # views.py from django.shortcuts import render from .models import Product from .filters import ProductFilter def product_list(request): """Display a filterable list of products.""" filter = ProductFilter(request.GET, queryset=Product.objects.all()) return render(request, 'my_app/template.html', {'filter': filter}) 

The request.GET dictionary holds the URL parameters. django-filter parses them and returns a filtered queryset.

You can also access the filtered results separately from the filter form itself.

 def product_list(request): filter = ProductFilter(request.GET, queryset=Product.objects.all()) # The filtered queryset is available as filter.qs return render(request, 'my_app/template.html', { 'filter': filter, 'products': filter.qs, }) 

In your template, render the filter form and iterate over the products. django-filter handles the form rendering automatically.

Integrating with Django REST Framework

django-filter provides a DRF-specific FilterSet and backend. The import path changes slightly.

 # filters.py from django_filters import rest_framework as filters from .models import Product class ProductFilter(filters.FilterSet): class Meta: model = Product fields = ('category', 'in_stock') 

Add DjangoFilterBackend to your view's filter_backends and set the filterset_class[reference:5].

 # views.py from rest_framework import generics from django_filters import rest_framework as filters from .models import Product from .serializers import ProductSerializer from .filters import ProductFilter class ProductList(generics.ListAPIView): queryset = Product.objects.all() serializer_class = ProductSerializer filter_backends = (filters.DjangoFilterBackend,) filterset_class = ProductFilter 

Now your API endpoint accepts query parameters like ?category=electronics∈_stock=true. The backend applies them to the queryset before serialization.

For a simpler setup, you can skip the FilterSet class entirely and use the filterset_fields shortcut[reference:6].

 class ProductList(generics.ListAPIView): queryset = Product.objects.all() serializer_class = ProductSerializer filter_backends = (filters.DjangoFilterBackend,) filterset_fields = ('category', 'in_stock') 

This is equivalent to creating a FilterSet with just those fields. It is convenient for basic filtering needs.

If you want to apply django-filter across every API view, add it to the DEFAULT_FILTER_BACKENDS setting[reference:7].

 # settings.py REST_FRAMEWORK = { 'DEFAULT_FILTER_BACKENDS': ( 'django_filters.rest_framework.DjangoFilterBackend', ), } 

This saves you from adding filter_backends to every individual view. It is a common pattern in larger API projects.

Common Installation Problems

Problem: "No module named 'django_filters'"

This error usually means pip installed the package for a different Python interpreter than the one running your project[reference:8]. The fix is to invoke pip through Python itself.

 python -m pip install django-filter 

This guarantees the package lands in the correct site-packages directory for the active interpreter.

Problem: Version conflict with Django

An old version of django-filter may not support your Django version. For example, django-filter 2.0.0 is incompatible with Django 3.1[reference:9]. Upgrading django-filter resolves the conflict.

 pip install --upgrade django-filter 

Problem: "Could not find a version that satisfies the requirement"

This appears when you pin a version that does not exist or is not available for your Python version. Remove the version pin and let pip choose the latest compatible release.

Problem: django-filter fails to build with Python 3.14

Very new Python releases sometimes break older package builds. Check the django-filter release notes for Python compatibility. If you are on Python 3.14, use the latest django-filter version or stay on Python 3.13 until support lands[reference:10].

Problem: Filters do not appear in the API

If filtering silently does nothing, check two things. First, 'django_filters' must be in INSTALLED_APPS. Second, the view must have DjangoFilterBackend in its filter_backends tuple. Both are required.

Best Practices

Keep FilterSets in a dedicated file. A filters.py module per app keeps filter logic separate from views and serializers.

Use explicit fields. The Meta.fields list controls what users can filter on. Never expose fields you have not reviewed.

Pin your version. Add django-filter to your requirements file with a specific version. This prevents unexpected behavior changes during deployment.

Test your filters. Write a few tests that pass query parameters and assert the returned queryset. Filters are easy to break during refactoring.

Combine with other backends. django-filter works alongside DRF's SearchFilter and OrderingFilter. Stack them in the filter_backends tuple for powerful query capabilities.

Conclusion

Installing django-filter in Python is a three-step process. Run pip install django-filter, add 'django_filters' to INSTALLED_APPS, and build your first FilterSet.

From there, the package scales with your project. Start with simple field filters. Add lookup expressions for range queries. Integrate with DRF for API filtering that feels natural to frontend developers.

The most common installation errors come from interpreter mismatches and missing app registration. Both are easy to fix once you know where to look.

With django-filter in your toolkit, your Django views and APIs become more flexible without adding custom query logic to every endpoint.