Elasticsearch Python Client (7.x Series)
raw JSON → 7.17.13 verified Tue May 12 auth: no en install: verified quickstart: stale
The `elasticsearch` client for Python provides a low-level client for Elasticsearch, supporting multiple major versions of the Elasticsearch server. This entry specifically focuses on the `7.x` series of the client, which is designed to be compatible with Elasticsearch server versions 7.x. The latest release in the 7.x series is 7.17.13. Elastic maintains different major versions of the client to align with server compatibility, with ongoing maintenance for older major versions like 7.x.
pip install 'elasticsearch<8' Common errors
error elasticsearch.exceptions.ConnectionError: ConnectionError(...) caused by MaxRetryError(... 'Failed to establish a new connection') ↓
cause The Python client could not establish a connection to the Elasticsearch server. This often means the server is not running, is running on a different host/port, or a firewall is blocking the connection.
fix
Verify that Elasticsearch is running and accessible from where your Python script is executed. Check the configured
host and port in your Elasticsearch client constructor. Ensure no firewall rules block access to the Elasticsearch port (default 9200). error TypeError: __init__() got an unexpected keyword argument 'basic_auth' ↓
cause You are using a client that is expected to be 7.x, but trying to use authentication arguments specific to the 8.x client (like `basic_auth`).
fix
For the 7.x client, use
http_auth=('username', 'password') for basic authentication. The basic_auth keyword argument was introduced in the 8.x client. error elasticsearch.exceptions.RequestError: RequestError(400, 'mapper_parsing_exception', 'failed to parse field') ↓
cause The data you are trying to index does not conform to the mapping of the target index, or there's an issue with the data format itself.
fix
Review your document's structure and data types against the existing Elasticsearch index mapping. Ensure fields contain values compatible with their defined types. If no mapping exists, Elasticsearch might infer one; check the inferred mapping. Use
es.indices.get_mapping(index='your_index') to inspect. Warnings
breaking Major version upgrade from 7.x to 8.x and above introduces significant breaking changes. The `_doc` type for indexing/getting documents is removed, and authentication parameters in the `Elasticsearch` client constructor (e.g., `http_auth` vs `basic_auth`) have changed. ↓
fix When upgrading, consult the official `elasticsearch-py` migration guide for your specific version. Update `index` and `get` calls to remove `_doc` (e.g., `es.index(index='my_index', id=1, document=doc)`) and adjust client instantiation for authentication (e.g., use `basic_auth` instead of `http_auth`).
gotcha By default, the client expects a secure (HTTPS) connection and will attempt SSL certificate verification. Connecting to local, unsecured, or self-signed HTTPS instances without proper configuration will lead to SSL errors. ↓
fix For development/local setups, use `verify_certs=False` and `ssl_show_warn=False` (or ensure `http_compress=True` if using HTTP). For production with HTTPS, provide valid `ca_certs` or ensure your system's certificate store is correctly configured. Example: `Elasticsearch(..., verify_certs=True, ca_certs='/path/to/certs.pem')`
deprecated The `sniff_on_start` and `sniff_on_connection_fail` parameters in the `Elasticsearch` client constructor are deprecated in favor of `node_callbacks` and explicit `sniff()` calls. ↓
fix While still functional in 7.x, for forward compatibility, consider transitioning to manual `es.sniff()` or implementing `node_callbacks` as described in the 8.x documentation if you anticipate upgrading.
Install
pip install 'elasticsearch==7.17.13' Install compatibility verified last tested: 2026-05-12
python os / libc variant status wheel install import disk
3.10 alpine (musl) 'elasticsearch<8' - - 0.33s 22.6M
3.10 alpine (musl) 'elasticsearch==7.17.13' - - 0.34s 22.6M
3.10 alpine (musl) elasticsearch - - 0.70s 33.5M
3.10 alpine (musl) elasticsearch7 - - - -
3.10 alpine (musl) elasticsearch8 - - - -
3.10 slim (glibc) 'elasticsearch<8' - - 0.23s 23M
3.10 slim (glibc) 'elasticsearch==7.17.13' - - 0.24s 23M
3.10 slim (glibc) elasticsearch - - 0.45s 34M
3.10 slim (glibc) elasticsearch7 - - - -
3.10 slim (glibc) elasticsearch8 - - - -
3.11 alpine (musl) 'elasticsearch<8' - - 0.45s 24.9M
3.11 alpine (musl) 'elasticsearch==7.17.13' - - 0.46s 24.9M
3.11 alpine (musl) elasticsearch - - 1.61s 37.5M
3.11 alpine (musl) elasticsearch7 - - - -
3.11 alpine (musl) elasticsearch8 - - - -
3.11 slim (glibc) 'elasticsearch<8' - - 0.43s 25M
3.11 slim (glibc) 'elasticsearch==7.17.13' - - 0.43s 25M
3.11 slim (glibc) elasticsearch - - 1.24s 38M
3.11 slim (glibc) elasticsearch7 - - - -
3.11 slim (glibc) elasticsearch8 - - - -
3.12 alpine (musl) 'elasticsearch<8' - - 0.61s 16.6M
3.12 alpine (musl) 'elasticsearch==7.17.13' - - 0.65s 16.6M
3.12 alpine (musl) elasticsearch - - 1.60s 29.0M
3.12 alpine (musl) elasticsearch7 - - - -
3.12 alpine (musl) elasticsearch8 - - - -
3.12 slim (glibc) 'elasticsearch<8' - - 0.62s 17M
3.12 slim (glibc) 'elasticsearch==7.17.13' - - 0.62s 17M
3.12 slim (glibc) elasticsearch - - 1.63s 29M
3.12 slim (glibc) elasticsearch7 - - - -
3.12 slim (glibc) elasticsearch8 - - - -
3.13 alpine (musl) 'elasticsearch<8' - - 0.60s 16.3M
3.13 alpine (musl) 'elasticsearch==7.17.13' - - 0.61s 16.3M
3.13 alpine (musl) elasticsearch - - 1.54s 28.4M
3.13 alpine (musl) elasticsearch7 - - - -
3.13 alpine (musl) elasticsearch8 - - - -
3.13 slim (glibc) 'elasticsearch<8' - - 0.58s 17M
3.13 slim (glibc) 'elasticsearch==7.17.13' - - 0.59s 17M
3.13 slim (glibc) elasticsearch - - 1.61s 29M
3.13 slim (glibc) elasticsearch7 - - - -
3.13 slim (glibc) elasticsearch8 - - - -
3.9 alpine (musl) 'elasticsearch<8' - - 0.26s 22.1M
3.9 alpine (musl) 'elasticsearch==7.17.13' - - 0.26s 22.1M
3.9 alpine (musl) elasticsearch - - 0.55s 30.5M
3.9 alpine (musl) elasticsearch7 - - - -
3.9 alpine (musl) elasticsearch8 - - - -
3.9 slim (glibc) 'elasticsearch<8' - - 0.23s 23M
3.9 slim (glibc) 'elasticsearch==7.17.13' - - 0.23s 23M
3.9 slim (glibc) elasticsearch - - 0.48s 31M
3.9 slim (glibc) elasticsearch7 - - - -
3.9 slim (glibc) elasticsearch8 - - - -
Imports
- Elasticsearch wrong
from elasticsearch7 import Elasticsearchcorrectfrom elasticsearch import Elasticsearch - TransportError wrong
from elasticsearch.exceptions import TransportErrorcorrectfrom elasticsearch import TransportError
Quickstart stale last tested: 2026-04-23
import os
from elasticsearch import Elasticsearch
# Connect to a local Elasticsearch 7.x instance
# Replace with your actual host, port, and auth details
ES_HOST = os.environ.get('ES_HOST', 'localhost')
ES_PORT = int(os.environ.get('ES_PORT', 9200))
ES_USER = os.environ.get('ES_USER', 'elastic')
ES_PASSWORD = os.environ.get('ES_PASSWORD', 'changeme')
# For local, unsecured ES, verify_certs=False might be needed.
# For production, ensure proper CA certs and security.
# In 7.x, http_auth is common for basic authentication.
es = Elasticsearch(
[
{'host': ES_HOST, 'port': ES_PORT}
],
http_auth=(ES_USER, ES_PASSWORD), # Use http_auth for 7.x
verify_certs=False,
ssl_show_warn=False # Suppress SSL warnings if verify_certs=False
)
# Check connection
print("Connected to Elasticsearch:", es.ping())
# Index a document
doc = {
'author': 'John Doe',
'text': 'Elasticsearch is a search engine.',
'timestamp': '2023-01-01'
}
response = es.index(index='my-test-index-7', id=1, document=doc)
print("Document indexed:", response['result'])
# Get a document
response = es.get(index='my-test-index-7', id=1)
print("Retrieved document:", response['_source'])
# Search for documents
search_body = {
'query': {
'match': {
'text': 'search engine'
}
}
}
response = es.search(index='my-test-index-7', body=search_body)
print(f"Found {response['hits']['total']['value']} hits:")
for hit in response['hits']['hits']:
print(hit['_source'])