Install & Compatibility
Where this runs
tested against v9.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.312s · 51.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.9s · import 1.226s · 52MB
51MB installed
● package 51MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Builder
✓ from es_client import Builder
This quickstart demonstrates how to initialize the es-client Builder with a configuration dictionary, establish a connection to an Elasticsearch cluster, and then retrieve the underlying Elasticsearch client to perform basic operations like checking cluster info and creating an index. Sensitive connection details are sourced from environment variables for security.
import os
from es_client import Builder
# Configure Elasticsearch connection using environment variables for sensitive data
config = {
'elasticsearch': {
'client': {
'hosts': os.environ.get('ES_HOSTS', 'https://localhost:9200').split(','),
'api_key': os.environ.get('ES_API_KEY', ''),
'ca_certs': os.environ.get('ES_CA_CERTS', ''), # e.g., '/etc/elasticsearch/certs/ca.crt'
'request_timeout': 60,
},
'other_settings': {
'master_only': False,
'username': os.environ.get('ES_USERNAME', ''),
'password': os.environ.get('ES_PASSWORD', ''),
}
},
'logging': {
'loglevel': 'INFO',
'logfile': '', # Path to log file, e.g., '/var/log/es_client.log'
'logformat': 'default',
}
}
builder = Builder(configdict=config)
try:
builder.connect()
client = builder.client # Get the connected Elasticsearch client instance
# Example: Check cluster info
info = client.info()
print("Connected to Elasticsearch cluster:", info['cluster_name'])
# Example: Create an index
index_name = "my_test_index"
if not client.indices.exists(index=index_name):
client.indices.create(index=index_name)
print(f"Index '{index_name}' created.")
else:
print(f"Index '{index_name}' already exists.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakinges-client v9.0.0 is a major version bump that replaced the `elasticsearch8` dependency with `elasticsearch9` and removed the `helpers` submodule. Code relying on `elasticsearch8` or the `es_client.helpers` submodule will break.fixUpdate your `pip install` to `elasticsearch9` and ensure your Elasticsearch cluster is version 9.x. Rewrite any code using the `helpers` submodule to use `elasticsearch.helpers` directly or the native `elasticsearch` client methods.
affects: >=9.0.0
breakingThe `elasticsearch-dsl` package is now integrated directly into the `elasticsearch` client as of `elasticsearch-py` v8.18.0. If you were using `elasticsearch-dsl` alongside `es-client`, you should uninstall `elasticsearch-dsl` and change imports from `elasticsearch_dsl` to `elasticsearch.dsl`.fixUninstall `elasticsearch-dsl` and modify import statements from `from elasticsearch_dsl import Search` to `from elasticsearch.dsl import Search`.
affects: elasticsearch-py >=8.18.0
gotchaURL paths in client configuration were not always respected, leading to connection issues or incorrect endpoint targeting.fixUpgrade to `es-client` v9.0.2 or later, or `v8.19.4` or later patches in the 8.x series. Verify your `hosts` configuration carefully, especially when using paths in the URL.
affects: <9.0.2 (for 9.x series) and <8.19.4 (for 8.x series)
gotchaes-client v8.19.0 introduced a `click` dependency that inadvertently broke compatibility with Python 3.8 and 3.9. While fixed in a subsequent patch, users on these Python versions should be aware.fixEnsure you are using `es-client` v8.19.2 or a later patch within the 8.x series to maintain compatibility with Python 3.8 and 3.9 if `click` related issues arise.
affects: 8.19.0 - 8.19.1
breakingUsing the Elasticsearch Python client version 9.0.0 or later (which es-client v9.x depends on) against an Elasticsearch 8.x server will fail due to incompatible APIs. Compatibility requires the server version to match or be newer.fixAlways upgrade your Elasticsearch cluster to version 9.x *before* upgrading your `es-client` library to 9.0.0 or later.
affects: es-client >=9.0.0 (when connecting to Elasticsearch <9.0.0)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'elasticsearch8'
Attempting to run `es-client` v9.x code with an environment or dependency list that still expects `elasticsearch8`, which was replaced by `elasticsearch9` in `es-client` v9.0.0.
fixEnsure `elasticsearch9` is installed and `es-client` is updated to a 9.x version. You might need `pip install elasticsearch9` and `pip install --upgrade es-client`.
AttributeError: 'Elasticsearch' object has no attribute 'helpers'
Trying to use the `helpers` submodule (e.g., `client.helpers.bulk`) directly from an `es-client` v9.x `client` instance. The `helpers` submodule was removed from `es_client` and the official `elasticsearch-py` client in v9.0.0.
fixImport `helpers` directly from `elasticsearch`: `from elasticsearch import helpers`. Then call functions like `helpers.bulk(client, actions)`.
ConnectionError: Connection refused
Incorrect Elasticsearch host configuration, network issues, firewall blocking, or credentials missing/incorrect. For `es-client` specifically, older versions (pre-9.0.2/8.19.4) sometimes mishandled URL paths.
fixVerify that your `configdict['elasticsearch']['client']['hosts']` contains the correct and accessible Elasticsearch endpoints. Ensure any required `api_key`, `username`, `password`, or `ca_certs` are correctly provided. If using URL paths, ensure `es-client` is v9.0.2+ or v8.19.4+.
TypeError: 'Builder' object is not callable
Attempting to use the `Builder` instance directly as the Elasticsearch client (e.g., `builder.info()`) before explicitly retrieving the client object.
fixAfter calling `builder.connect()`, you must access the actual Elasticsearch client instance via `client = builder.client`. All subsequent Elasticsearch API calls should be made using this `client` object.
Upgrade
Version history
9.0.1latest on PyPI · released Oct 3, 2025
Audit
Dependencies
elasticsearch9requiredCore dependency for connecting to Elasticsearch 9.x clusters. This replaced elasticsearch8 in v9.0.0.
tiered-debugrequiredUsed for structured logging and debugging within the client.
certifirequiredEnsures up-to-date CA certificates for secure connections.
clickrequiredUsed for command-line interface utilities; compatibility with older Python versions was a past concern in 8.x series.