{"id":6343,"library":"django-elasticsearch-dsl","title":"Django Elasticsearch DSL","description":"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.","status":"active","version":"9.0","language":"en","source_language":"en","source_url":"https://github.com/django-es/django-elasticsearch-dsl","tags":["django","elasticsearch","search","orm","full-text-search"],"install":[{"cmd":"pip install django-elasticsearch-dsl","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for interacting with Elasticsearch; this library is a wrapper around it.","package":"elasticsearch-dsl"},{"reason":"The library is a Django application and requires a compatible Django version.","package":"Django"}],"imports":[{"symbol":"Document","correct":"from django_elasticsearch_dsl import Document"},{"symbol":"Index","correct":"from django_elasticsearch_dsl import Index"},{"symbol":"registry","correct":"from django_elasticsearch_dsl.registries import registry"},{"note":"Document fields are imported directly from elasticsearch-dsl, not django-elasticsearch-dsl.","wrong":"from django_elasticsearch_dsl import fields","symbol":"fields","correct":"from elasticsearch_dsl import fields"}],"quickstart":{"code":"import os\n\n# models.py (example_app)\nfrom django.db import models\n\nclass Article(models.Model):\n    title = models.CharField(max_length=255)\n    body = models.TextField()\n    published = models.BooleanField(default=False)\n\n    def __str__(self):\n        return self.title\n\n# documents.py (example_app)\nfrom django_elasticsearch_dsl import Document, Index\nfrom django_elasticsearch_dsl.registries import registry\nfrom elasticsearch_dsl import fields\n\nfrom .models import Article\n\n# Define a custom index\narticle_index = Index('articles')\narticle_index.settings(number_of_shards=1, number_of_replicas=0)\n\n@registry.register_document\n@article_index.document\nclass ArticleDocument(Document):\n    id = fields.IntegerField(attr='id')\n    title = fields.TextField(\n        analyzer='english',\n        fields={'raw': fields.KeywordField()}\n    )\n    body = fields.TextField(\n        analyzer='english',\n        fields={'raw': fields.KeywordField()}\n    )\n    published = fields.BooleanField()\n\n    class Django:\n        model = Article\n        fields = ['title', 'body', 'published']\n\n# In settings.py:\n# ELASTICSEARCH_DSL = {\n#     'default': {\n#         'hosts': os.environ.get('ES_HOST', 'localhost:9200'),\n#         'timeout': 60\n#     }\n# }\n# ELASTICSEARCH_DSL_SIGNAL_PROCESSOR = 'django_elasticsearch_dsl.signals.RealTimeSignalProcessor'\n\n# To rebuild index:\n# python manage.py search_index --rebuild\n\n# Example search query:\n# from example_app.documents import ArticleDocument\n# s = ArticleDocument.search().query('match', title='test article')\n# response = s.execute()\n# for hit in response:\n#     print(hit.title)","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":"8.0+"},{"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).","message":"The 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.","severity":"breaking","affected_versions":"7.x+"},{"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.","message":"Incorrect 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}