Python Elasticsearch Client

Official low-level client for Elasticsearch. Its goal is to provide common ground for all Elasticsearch-related code in Python; because of this it tries to be opinion-free and very extendable.


Install the elasticsearch package with pip:

$ python -m pip install elasticsearch

If your application uses async/await in Python you can install with the async extra:

$ python -m pip install elasticsearch[async]

Read more about how to use asyncio with this project.


Language clients are forward compatible; meaning that clients support communicating with greater minor versions of Elasticsearch.

Elastic language clients are also backwards compatible with lesser supported minor Elasticsearch versions.

If you have a need to have multiple versions installed at the same time older versions are also released as elasticsearch2 and elasticsearch5.

Example use

>>> from datetime import datetime
>>> from elasticsearch import Elasticsearch

# by default we connect to localhost:9200
>>> es = Elasticsearch()

# create an index in elasticsearch, ignore status code 400 (index already exists)
>>> es.indices.create(index='my-index', ignore=400)
{'acknowledged': True, 'shards_acknowledged': True, 'index': 'my-index'}

# datetimes will be serialized
>>> es.index(index="my-index", id=42, body={"any": "data", "timestamp":})
{'_index': 'my-index',
 '_type': '_doc',
 '_id': '42',
 '_version': 1,
 'result': 'created',
 '_shards': {'total': 2, 'successful': 1, 'failed': 0},
 '_seq_no': 0,
 '_primary_term': 1}

# but not deserialized
>>> es.get(index="my-index", id=42)['_source']
{'any': 'data', 'timestamp': '2019-05-17T17:28:10.329598'}

Elastic Cloud (and SSL) use-case:

>>> from elasticsearch import Elasticsearch
>>> es = Elasticsearch(cloud_id="<some_long_cloud_id>", http_auth=('elastic','yourpassword'))

Using SSL Context with a self-signed cert use-case:

>>> from elasticsearch import Elasticsearch
>>> from ssl import create_default_context

>>> context = create_default_context(cafile="path/to/cafile.pem")
>>> es = Elasticsearch("https://elasticsearch.url:port", ssl_context=context, http_auth=('elastic','yourpassword'))


The client's features include:

  • translating basic Python data types to and from json (datetimes are not decoded for performance reasons)
  • configurable automatic discovery of cluster nodes
  • persistent connections
  • load balancing (with pluggable selection strategy) across all available nodes
  • failed connection penalization (time based - failed connections won't be retried until a timeout is reached)
  • support for ssl and http authentication
  • thread safety
  • pluggable architecture