Registry / database / django-elasticsearch-dsl

django-elasticsearch-dsl

library9.0pypypiunverified

django-elasticsearch-dsl is a Django application that wraps elasticsearch-dsl-py to provide an easy way to integrate Elasticsearch with Django models. It simplifies document definition, index management, and provides signal processors for automatic indexing of model changes. The current version is 9.0, and the project maintains an active release cadence with regular updates and support for new Django and Elasticsearch versions.

database web-framework serialization

pip install django-elasticsearch-dsl

github ↗package ↗

INSTALL

IMPORT

SIG · DJANGO-ELASTICSEAR

django-elasticsearch-dsl

databasepythonv9.0

Install

2.9s avg

Import

—

Disk

32MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 33.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.9s · import 0.000s · 34MB

32MB installed

● package 32MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Document

✓ from django_elasticsearch_dsl import Document

✗ from django_elasticsearch_dsl import Document

To get started, define your Elasticsearch settings in `settings.py`. Create a `Document` subclass for your Django model, register it with the `registry`, and define its fields using `elasticsearch_dsl.fields`. You can then rebuild your Elasticsearch index using the `search_index` management command and perform searches through the `Document`'s `.search()` method. Remember to configure a signal processor for real-time indexing.

import os # models.py (example_app) from django.db import models class Article(models.Model): title = models.CharField(max_length=255) body = models.TextField() published = models.BooleanField(default=False) def __str__(self): return self.title # documents.py (example_app) from django_elasticsearch_dsl import Document, Index from django_elasticsearch_dsl.registries import registry from elasticsearch_dsl import fields from .models import Article # Define a custom index article_index = Index('articles') article_index.settings(number_of_shards=1, number_of_replicas=0) @registry.register_document @article_index.document class ArticleDocument(Document): id = fields.IntegerField(attr='id') title = fields.TextField( analyzer='english', fields={'raw': fields.KeywordField()} ) body = fields.TextField( analyzer='english', fields={'raw': fields.KeywordField()} ) published = fields.BooleanField() class Django: model = Article fields = ['title', 'body', 'published'] # In settings.py: # ELASTICSEARCH_DSL = { # 'default': { # 'hosts': os.environ.get('ES_HOST', 'localhost:9200'), # 'timeout': 60 # } # } # ELASTICSEARCH_DSL_SIGNAL_PROCESSOR = 'django_elasticsearch_dsl.signals.RealTimeSignalProcessor' # To rebuild index: # python manage.py search_index --rebuild # Example search query: # from example_app.documents import ArticleDocument # s = ArticleDocument.search().query('match', title='test article') # response = s.execute() # for hit in response: # print(hit.title)

Debug

Known issues

breakingVersion 8.0 dropped support for Python 2.7, 3.6, 3.7. It now requires Python >=3.9. It also dropped support for Django versions 1.11, 2.x, 3.x, and 4.0, now requiring Django >=4.1. This release also introduces support for Elasticsearch 8.

fix

Upgrade your Python environment to >=3.9 and Django to >=4.1 before upgrading django-elasticsearch-dsl to 8.0+. If using Elasticsearch, ensure compatibility with Elasticsearch 8.

affects: 8.0+

breakingThe major version bump from 6.x to 7.x aligned with elasticsearch-dsl-py's move from `DocType` to `Document` (and dropping compatibility with older Elasticsearch server versions, notably <6.x). This requires updating document definitions if migrating from a very old version.

fix

Review your `DocType` definitions and convert them to `Document` subclasses. Ensure your Elasticsearch server is version 6.x or newer (and 7.x is recommended for `django-elasticsearch-dsl` 7.x).

affects: 7.x+

gotchaIncorrect or missing Elasticsearch connection settings in `settings.py` (ELASTICSEARCH_DSL) is a common issue. If connections are not properly defined, operations will fail silently or with connection errors.

fix

Always ensure your `ELASTICSEARCH_DSL` dictionary in `settings.py` is correctly configured with at least a 'default' host. Use environment variables for sensitive data like hostnames or credentials.

affects: All

gotchaFor real-time indexing of Django model changes (create, update, delete), you must configure a signal processor, e.g., `ELASTICSEARCH_DSL_SIGNAL_PROCESSOR = 'django_elasticsearch_dsl.signals.RealTimeSignalProcessor'`. Without it, your Elasticsearch index will become stale.

fix

Add `ELASTICSEARCH_DSL_SIGNAL_PROCESSOR` to your `settings.py` and choose an appropriate signal processor. For production, consider using an asynchronous processor like CelerySignalProcessor for better performance.

affects: All

Upgrade

Version history

9.0latest on PyPI · released Jul 23, 2025

Audit

Dependencies

elasticsearch-dslrequiredCore dependency for interacting with Elasticsearch; this library is a wrapper around it.

DjangorequiredThe library is a Django application and requires a compatible Django version.

Agent activity

29 hits · last 30 days

node

Resources

githubhttps://github.com/sabricot/django-elasticsearch-dsl ↗

packagehttps://pypi.org/project/django-elasticsearch-dsl/ ↗