Install¶

django-search-query is the core query language, independent of any particular UI, admin integration, or search backend; add it to any Django project’s environment. django-admin-search-query is the optional admin integration built on top of it – reach for it only when you want structured search on an admin changelist page.

Install django-search-query:

$ uv add django-search-query

Then build a query from a search string:

from django_search_query import search_query_to_q
from django_search_query.registry import FieldRegistry, FieldSpec

registry = FieldRegistry(specs=(FieldSpec(name="status", kind="enum"),))
q = search_query_to_q(
    "status:open",
    registry=registry,
    field_map={"status": "status"},
    default_fields=("title", "body"),
)
Article.objects.filter(q)

Install django-search-query:

$ pip install django-search-query

Then build a query from a search string:

from django_search_query import search_query_to_q
from django_search_query.registry import FieldRegistry, FieldSpec

registry = FieldRegistry(specs=(FieldSpec(name="status", kind="enum"),))
q = search_query_to_q(
    "status:open",
    registry=registry,
    field_map={"status": "status"},
    default_fields=("title", "body"),
)
Article.objects.filter(q)

Install django-admin-search-query:

$ uv add django-admin-search-query

Then wire it into the Django admin:

from django.contrib import admin

from django_admin_search_query import SearchQueryAdminMixin
from django_search_query.registry import FieldRegistry, FieldSpec


@admin.register(Article)
class ArticleAdmin(SearchQueryAdminMixin, admin.ModelAdmin):
    search_query_registry = FieldRegistry(specs=(FieldSpec(name="status", kind="enum"),))
    search_query_field_map = {"status": "status"}
    search_query_default_fields = ("title", "body")

Install django-admin-search-query:

$ pip install django-admin-search-query

Then wire it into the Django admin:

from django.contrib import admin

from django_admin_search_query import SearchQueryAdminMixin
from django_search_query.registry import FieldRegistry, FieldSpec


@admin.register(Article)
class ArticleAdmin(SearchQueryAdminMixin, admin.ModelAdmin):
    search_query_registry = FieldRegistry(specs=(FieldSpec(name="status", kind="enum"),))
    search_query_field_map = {"status": "status"}
    search_query_default_fields = ("title", "body")

INSTALLED_APPS = [
    "django.contrib.contenttypes",
    "django.contrib.auth",
    "django.contrib.admin",
    "django.contrib.messages",
    "django.contrib.sessions",
    "django_search_query",
    "django_admin_search_query",  # optional: admin integration
    ...
]

django_admin_search_query needs django.contrib.admin (and its own dependencies, contenttypes, auth, messages, sessions) already installed – skip it if you only use the core query language.

Developmental releases¶

New versions are published to PyPI as alpha, beta, or release candidates. In their versions you will see notation like a1, b1, and rc1, respectively. 1.0.0b4 would mean the 4th beta release of 1.0.0 before general availability.

pip:

$ pip install --upgrade --pre django-search-query

pipx:

$ pipx install --suffix=@next 'django-search-query' --pip-args '\--pre' --force

uv:

$ uv add django-search-query --prerelease allow

uvx:

$ uvx --from 'django-search-query' --prerelease allow django-search-query

See Tutorial for what to do once the package is installed.