version coverage license

This is a Django integration of Select2.

The app includes Select2 driven Django Widgets.


Documentation available at


Django’s admin comes with builtin support for Select2 via the autocomplete_fields feature.


Install django-select2:

python3 -m pip install django-select2

Add django_select2 to your INSTALLED_APPS in your project settings.

Add django_select to your URL root configuration:

from django.urls import include, path

urlpatterns = [
    # … other patterns
    path("select2/", include("django_select2.urls")),
    # … other patterns

django-select2 requires a cache backend which is persistent across all application servers..

This means that the DummyCache backend will not work!

The default cache backend is LocMemCache, which is persistent across a single node. For projects with a single application server this will work fine, however you will run into issues when you scale up into multiple servers.

Below is an example setup using Redis, which is a solution that works for multi-server setups:

Make sure you have a Redis server up and running:

# Debian
sudo apt-get install redis-server

# macOS
brew install redis

# install Redis python client
python3 -m pip install django-redis

Next, add the cache configuration to your as follows:

    # … default cache config and others
    "select2": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",

# Tell select2 which cache configuration to use:


A custom timeout for your cache backend, will serve as an indirect session limit. Auto select fields will stop working after, once the cache has expired. It’s recommended to use a dedicated cache database with an adequate cache replacement policy such as LRU, FILO, etc.

External Dependencies

  • jQuery is not included in the package since it is expected that in most scenarios this would already be available.

Quick Start

Here is a quick example to get you started:

First make sure you followed the installation instructions above. Once everything is setup, let’s start with a simple example.

We have the following model:

from django.conf import settings
from django.db import models

class Book(models.Model):
    author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
    co_authors = models.ManyToManyField(settings.AUTH_USER_MODEL, related_name='co_authored_by')

Next, we create a model form with custom Select2 widgets.

from django import forms
from django_select2 import forms as s2forms

from . import models

class AuthorWidget(s2forms.ModelSelect2Widget):
    search_fields = [

class CoAuthorsWidget(s2forms.ModelSelect2MultipleWidget):
    search_fields = [

class BookForm(forms.ModelForm):
    class Meta:
        model = models.Book
        fields = "__all__"
        widgets = {
            "author": AuthorWidget,
            "co_authors": CoAuthorsWidget,

A simple class based view will do, to render your form:

from django.views import generic

from . import forms, models

class BookCreateView(generic.CreateView):
    model = models.Book
    form_class = forms.BookForm
    success_url = "/"

Make sure to add the view to your

from django.urls import include, path

from . import views

urlpatterns = [
    # … other patterns
    path("select2/", include("django_select2.urls")),
    # … other patterns
    path("book/create", views.BookCreateView.as_view(), name="book-create"),

Finally, we need a little template, myapp/templates/myapp/book_form.html

<!DOCTYPE html>
<html lang="en">
    <title>Create Book</title>
    {{ }}
        input, select {width: 100%}
    <h1>Create a new Book</h1>
    <form method="POST">
        {% csrf_token %}
        {{ form.as_p }}
        <input type="submit">
    <script src=""></script>
    {{ }}

Done - enjoy the wonders of Select2!


See Github releases.

All Contents


Indices and tables