Install & Compatibility
Where this runs
tested against v7.17.13 · 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
py 3.10
9/11 runs
9/11 runs
py 3.11
9/11 runs
9/11 runs
py 3.12
9/11 runs
9/11 runs
py 3.13
9/11 runs
9/11 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Elasticsearch
✓ from elasticsearch import Elasticsearch
✗ from elasticsearch7 import Elasticsearch
The PyPI package is 'elasticsearch', not 'elasticsearch7'. Pinning to <8 ensures the 7.x client.
TransportError
✓ from elasticsearch import TransportError
✗ from elasticsearch.exceptions import TransportError
Exceptions are directly available under the main 'elasticsearch' module in 7.x.
This quickstart demonstrates how to connect to an Elasticsearch 7.x instance, check its status, index a simple document, retrieve it by ID, and perform a basic full-text search. It includes common connection parameters for local or secured instances.
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'])
elasticsearch --version
Debug
Known issues
breakingMajor 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.fixWhen 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`).
affects: All versions migrating from 7.x to 8.x+
gotchaBy 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.fixFor 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')`
affects: All 7.x versions
deprecatedThe `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.fixWhile 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.
affects: 7.17 and later (deprecated in 8.x, but the 7.x client might issue warnings if you enable deprecated warnings)
Errors
Common errors & fixes
elasticsearch.exceptions.ConnectionError: ConnectionError(...) caused by MaxRetryError(... 'Failed to establish a new connection')
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.
fixVerify 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).
TypeError: __init__() got an unexpected keyword argument 'basic_auth'
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`).
fixFor the 7.x client, use `http_auth=('username', 'password')` for basic authentication. The `basic_auth` keyword argument was introduced in the 8.x client. elasticsearch.exceptions.RequestError: RequestError(400, 'mapper_parsing_exception', 'failed to parse field')
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.
fixReview 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.
Upgrade
Version history
9.4.1latest on PyPI · released May 26, 2026
Audit
Dependencies
No dependency data recorded yet.