---
id: elasticsearch8-dsl
version: "8.12.0"
license: Apache-2.0
license_treatment: permissive
maintenance: abandoned
---

# elasticsearch8-dsl — Python client for Elasticsearch

License: permissive · Maintenance: abandoned · Downloads: 118.6K/mo

## What it is and what it does

elasticsearch8-dsl is a Python wrapper around the official elasticsearch8 client that replaces verbose JSON dict-based query construction with a chainable, Pythonic API. Instead of manually nesting dictionaries to build bool queries, filters, and aggregations, you write method chains that the library translates to equivalent Elasticsearch JSON DSL. It also provides optional document mapping and persistence—you can define Python classes with typed fields that mirror Elasticsearch mappings, then save and retrieve documents as Python objects.

The library stays structurally close to Elasticsearch's native DSL terminology, so queries remain recognizable to anyone familiar with the JSON syntax. It includes a Search class for query building, aggregation support, and a Document base class for object-relational mapping. You can also convert between Search objects and raw dicts, allowing gradual migration from pure elasticsearch8 code.

Use it for:

- Build complex Elasticsearch queries programmatically without manually constructing nested JSON dicts.
- Define document schemas with typed fields and save/retrieve them as Python objects instead of raw dicts.
- Add filters, aggregations, and query clauses dynamically to a search object before execution.
- Migrate incrementally from elasticsearch8 by wrapping existing query dicts and modifying them via the DSL.
- Implement custom document methods and lifecycle hooks for domain logic.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A high-level Python query builder for Elasticsearch that translates idiomatic Python expressions into Elasticsearch JSON DSL queries, plus optional document mapping and persistence.

No. The repository is archived and abandoned with no releases since 2024-01-19 and last commit on 2025-04-18. While the code is permissively licensed and currently has no known vulnerabilities, the lack of active development means security patches, compatibility fixes, and bug fixes will not be forthcoming. Use only if maintaining a legacy application already on this version.

## Install

pip install elasticsearch8-dsl
uv add elasticsearch8-dsl
poetry add elasticsearch8-dsl

## Installing elasticsearch8-dsl

Before you install: Low install friction with only two runtime dependencies (python-dateutil and elasticsearch8). However, the repository is archived and marked abandoned, with the last commit on 2025-04-18 and no releases since 2024-01-19—maintenance has effectively stopped.

License in practice: Licensed under Apache-2.0 (permissive), allowing use in commercial and proprietary projects with minimal restrictions beyond attribution and liability disclaimers.

Quickstart:

pip install elasticsearch8-dsl

from elasticsearch8_dsl import Search
from elasticsearch import Elasticsearch

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

Requires a running Elasticsearch 8.x instance; the library version must match the major version of your Elasticsearch server.

Verify before relying:

- Whether the abandoned status and lack of recent releases pose a risk for future Elasticsearch server compatibility.
- Whether security patches or bug fixes will be backported if vulnerabilities are discovered in dependencies.
- Current production usage and whether alternatives are actively maintained.

## Package facts

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

## Tags

elasticsearch query builder python, elasticsearch dsl python, elasticsearch orm python, elasticsearch document mapping, elasticsearch query abstraction, elasticsearch python client wrapper, elasticsearch aggregation builder, elasticsearch, query-builder, orm

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