elasticsearch-dsl

What it is and what it does

Elasticsearch DSL is a high-level query builder that sits on top of the elasticsearch client. It lets you construct Elasticsearch queries and aggregations using Python method chains and class definitions instead of writing nested JSON dictionaries, making queries more readable and less error-prone. It also provides optional document persistence—you can define Python classes that map to Elasticsearch indices, with field types, custom methods, and automatic serialization.

As of version 8.18.0, this package is deprecated and its functionality has been integrated directly into the elasticsearch library. The 8.18.0 release automatically redirects imports, so existing code will continue to run, but new projects should use elasticsearch directly. The package is no longer actively maintained.

Use it for:

• Building complex search queries programmatically without manually constructing nested JSON structures.
• Defining Elasticsearch document schemas and mappings as Python classes with type hints and custom methods.
• Gradually migrating from raw elasticsearch dict-based queries by converting to Search objects and modifying them.
• Retrieving, saving, and managing documents as Python objects with automatic field mapping.

Worth the install?

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

Provides a high-level Python API for building and executing Elasticsearch queries using a DSL instead of raw JSON, plus optional object-relational mapping for documents.

No—do not install this package for new projects. Version 8.18.0 is a deprecation notice: the package is abandoned and its functionality is now part of elasticsearch. Install elasticsearch directly instead. Existing code using older versions may continue to work, but migration is strongly recommended.

Install

elasticsearch-dsl on PyPI

pip install elasticsearch-dsl

uv add elasticsearch-dsl

poetry add elasticsearch-dsl

Installing elasticsearch-dsl

Before you install

Low install friction with four stable runtime dependencies. However, the package is abandoned as of 8.18.0 and functionality has been integrated into the official client; migration is recommended.

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions.

Quickstart

pip install elasticsearch

from elasticsearch import Elasticsearch
from elasticsearch_dsl import Search

client = Elasticsearch("https://localhost:9200")
s = Search(using=client, index="my-index").filter("term", category="search")
response = s.execute()

Requires Elasticsearch server running and accessible; Python >=3.8.

Verify before relying

• Whether existing code using elasticsearch-dsl will continue to work without modification beyond import path changes.
• Long-term support timeline for the redirect shim in 8.18.0 before it is removed entirely.
• Compatibility guarantees between elasticsearch-dsl 8.18.0 and future elasticsearch versions.

Package facts

Evidence: elasticsearch_dsl-8.18.0-py3-none-any.whl

Tags

More Database packages