---
id: elasticsearch-dsl
version: "8.18.0"
license: Apache-2.0
license_treatment: permissive
maintenance: abandoned
---

# elasticsearch-dsl — Python client for Elasticsearch

License: permissive · Maintenance: abandoned · Downloads: 8.9M/mo

## 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 above — 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

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

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: abandoned
- Downloads: 8.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

elasticsearch query builder, elasticsearch python dsl, elasticsearch orm mapping, elasticsearch search abstraction, elasticsearch document persistence, elasticsearch aggregations python, deprecated, elasticsearch, query-builder

[View on SkillFed](https://skillfed.io/packages/elasticsearch-dsl) · [View on PyPI](https://pypi.org/project/elasticsearch-dsl/)