Skip to main content

A lightweight Python client for ElasticSearch, including a dump and import tool for indexes

Project description

WARNING: There is an official client

ElasticSearch now has an official Python API. For new projects, I strongly recommend you to use it.

You can install the official API with:
$ easy_install elasticsearch

Check out for more info.


ESClient is a Python library that uses the ElasticSearch REST API. It is meant to be lightweight and be close to the actual REST API in terms of usage.

With ESClient comes two scripts that are installed in your /usr/local/bin:

  • esdump – Use this script to dump one or more indexes to a file (or stdout)
  • esimport – Use this script to import a dump

The only shortage with these two tools is that they do not make a backup of the mappings yet. This is however planned for an upcoming version.



To install:

python install

You can also install ESClient with easy_install or pip. The following commands will install the latest released version of ESClient:

$ easy_install esclient

Or with pip:

$ pip install esclient


Please take a look at the file for usage examples. This code at least covers all the API methods that are implemented. As soon as the API reaches stability I will put more time into writing decent documentation. I advice you to keep the ElasticSearch documentation at hand when you start using this library. The documentation strings in the code should be very useful.

Unit tests can be used for unit testing. You can directly run this file if you have an ElasticSearch instance running on localhost.

Bug Tracker and Issues

If you find a bug or any other issue you may create an issue on GitHub!

Roadmap / TODO

My target is to reach a stable 1.0 release. Currently on the roadmap to reach such a 1.0 release are:

  • Implementing most or even all the API methods
  • Adding support for backing up the mappings with esdump and esimport
  • Adding option to esdump to save data into multiple files, with names based on the name of the source index


Licensed under the New BSD License. See also the LICENSE file


This client library was written by Erik-Jan van Baaren ( Others have contributed bugfixes or extensions too (thanks!) The style of this library is inspired by pyelasticsearch.


  • ESClient uses the excellent requests library.
  • The unit tests only work on Python 2.7 (one test will fail on 2.6)
  • The code is tested mostly on Python 2.6 and 2.7



  • Added esdump script, which can dump indexes to a (optionally compressed) file or stdout by using the new scan and scroll methods


  • Added two methods: scan and scroll. With these methods you can now perform scan queries and scroll through the results.


  • Bugfixing


  • fixed an issue where the dependency on the requests library was not automatically procesed by easy_install / pip


  • Refactored the bulk API to use more standard methods from ESClient
  • fixed some typos in code


  • Added bulk API + unit tests (thanks to isnowfy)


  • Added API method: index_exists


  • Better error handling (by using _parse_json_response() method everywhere)
  • Added API methods: get_mapping, put_mapping


  • Added API methods: status, flush
  • some code improvements / beautifying


  • Removed option to choose between JSON or hierachy of Python objects. It would have created too much hassle.
  • Added API methods: mget, open+close index, create_alias, delete_alias
  • small fixes here and there


  • Added docstring to the get API
  • made sure that removes old MANIFEST file before making new package
  • fixed version string in


From now on I will conform to the Semantic Versioning Guidelines outlined on this site: In that spirit, I bumped the minor version to 0.1.0 and will keep doing so until public API stability is reached.


First official release that was published to PyPI. Alpha quality, but with working unit tests for each API method.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ESClient, version 0.5.8
Filename, size File type Python version Upload date Hashes
Filename, size ESClient-0.5.8.macosx-10.9-intel.exe (78.4 kB) File type Windows Installer Python version any Upload date Hashes View hashes
Filename, size ESClient-0.5.8.tar.gz (13.6 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page