modelsearch

What it is and what it does

Django ModelSearch is a search indexing layer for Django that lets you index your models into Elasticsearch, OpenSearch, or your existing database (PostgreSQL FTS, MySQL FTS, MariaDB FTS, SQLite FTS5) and then query them through the familiar Django ORM. Instead of writing raw search queries, you call `.search()` on a QuerySet just like you would `.filter()`, and the library translates that into the appropriate backend query.

It was built into Wagtail CMS since 2014 and extracted as a standalone package in March 2025. The library handles index synchronization via Django signals, supports zero-downtime index rebuilds using aliases, and integrates with Django's pagination and filtering ecosystem. You define searchable fields on your models with optional per-field boosting, filter fields for fast faceting, and can pull content from related models into the index.

Use it for:

• Build a product catalog search that works across PostgreSQL, Elasticsearch, or SQLite without rewriting query logic for each backend.
• Add autocomplete and fuzzy search to a Django admin or user-facing search form with faceted results.
• Index large text fields (articles, documentation, logs) and search them with phrase queries and field-specific relevance tuning.
• Migrate search from database FTS to Elasticsearch for performance without changing application code.
• Combine full-text search with Django filters and pagination in a single QuerySet chain.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Indexes Django models into Elasticsearch, OpenSearch, or native database full-text search, then queries them through the Django ORM with support for filtering, faceting, and fuzzy search.

Yes. The package is actively maintained, has low install friction, carries a permissive license, and solves a real problem—letting you write search queries in Django ORM syntax regardless of backend. It's production-ready (marked stable, extracted from Wagtail's proven codebase), has no known vulnerabilities, and supports modern Python versions. Install it if you need flexible, backend-agnostic search on Django models.

Install

modelsearch on PyPI

pip install modelsearch

uv add modelsearch

poetry add modelsearch

Installing modelsearch

Before you install

Low friction: pure Python wheel with only Django and django-tasks as runtime dependencies. Actively maintained since March 2025 with recent commits and no known vulnerabilities.

License in practice

BSD-3-Clause (permissive): you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install modelsearch

# settings.py
INSTALLED_APPS = [
    'modelsearch',
    'django.contrib.postgres',  # if using PostgreSQL
]

# models.py
from modelsearch import index
from modelsearch.queryset import SearchableQuerySetMixin

class SongQuerySet(SearchableQuerySetMixin, models.QuerySet):
    pass

class Song(index.Indexed, models.Model):
    name = models.TextField()
    search_fields = [index.SearchField('name', boost=2.0)]
    objects = SongQuerySet.as_manager()

# Then search
Song.objects.search("query")

Requires Python 3.10+; if using PostgreSQL, django.contrib.postgres must be in INSTALLED_APPS; run `django-admin rebuild_modelsearch_index` to initialize indexes.

Verify before relying

• Whether django-tasks is a hard runtime requirement or optional for background indexing.
• Performance characteristics and scaling limits with large datasets or high query volume.
• Compatibility matrix details for specific Elasticsearch/OpenSearch versions beyond the documented 7.x, 8.x, 9.x and 2.x, 3.x ranges.

Package facts

Evidence: modelsearch-1.3.2-py3-none-any.whl

Tags

More Python Modules packages