elasticsearch9

library9.4.1pypypi✓ verified 84d ago

Official low-level Python client for Elasticsearch (version 9.x). Provides a thin wrapper over the Elasticsearch REST API, handling request serialization, connection pooling, and error handling. Requires Python >= 3.10. Released by Elastic with quarterly cadence.

search database

pip install elasticsearch9

github ↗homepage ↗

INSTALL

IMPORT

SIG · ELASTICSEARCH9

elasticsearch9

searchpythonv9.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Elasticsearch

✓ from elasticsearch9 import Elasticsearch

✗ from elasticsearch import Elasticsearch

elasticsearch is the deprecated client; always use elasticsearch9

helpers

✓ from elasticsearch9 import helpers

✗ from elasticsearch.helpers import scan

helpers are now under elasticsearch9, not elasticsearch

Create a client and ping the cluster. Uses environment variables for credentials.

import os from elasticsearch9 import Elasticsearch client = Elasticsearch( os.environ.get('ELASTICSEARCH_URL', 'http://localhost:9200'), api_key=os.environ.get('ELASTICSEARCH_API_KEY', ''), verify_certs=False # For dev only ) print(client.info())

Debug

Known issues

breakingAll modules and classes are under 'elasticsearch9' namespace. Importing from 'elasticsearch' will use the old deprecated client (v7/8) and break in v9.

fix

Always use 'from elasticsearch9 import Elasticsearch'

affects: >=9.0.0

breakingSSL certificate verification is enabled by default. If you use self-signed certs in dev, you must set verify_certs=False or provide a CA bundle, otherwise connections will fail with SSL errors.

fix

Elasticsearch(..., verify_certs=False) or configure ssl_assert_fingerprint

affects: >=9.0.0

deprecatedThe 'sniff_on_start', 'sniff_on_connection_fail', and 'sniffer_timeout' parameters are deprecated and will be removed in a future version. Use the Sniffer class from elastic_transport instead.

fix

from elastic_transport import Sniffer

affects: >=9.0.0

gotchaAPI key authentication requires the 'api_key' parameter, not 'headers'. Passing headers directly will not trigger the API key auth flow and may cause silent failures.

fix

Elasticsearch(..., api_key='id:api_key')

affects: >=9.0.0

breakingElasticsearch 9 changed the format of search results. The 'hits' dict no longer includes '_index' and '_type' by default. Use 'doc_type' parameter or modern mapping.

fix

Access results via response['hits']['hits'] and extract fields from '_source'

affects: >=9.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'elasticsearch'

You installed elasticsearch9 but tried importing from 'elasticsearch' (the old package).

fix

Uninstall both: pip uninstall elasticsearch elasticsearch9; then reinstall: pip install elasticsearch9

elasticsearch9.exceptions.ConnectionError: ConnectionError(<urllib3.connection.HTTPSConnection object ...) caused by: SSLError([SSL: CERTIFICATE_VERIFY_FAILED]

Default SSL verification fails against self-signed certificates.

fix

Add verify_certs=False to Elasticsearch constructor, or set SSL_CERT_FILE env variable.

elasticsearch9.exceptions.NotFoundError: NotFoundError(404, 'index_not_found_exception')

Trying to read/write to a non-existent index. Common when index name is misspelled or auto-creation is disabled.

fix

Create the index first: client.indices.create(index='my-index', ignore=400)

elasticsearch9.exceptions.RequestError: RequestError(400, 'mapper_parsing_exception', 'failed to parse field')

Sending a document with a field type that conflicts with the mapping.

fix

Update the mapping or ensure the field value matches the expected type (e.g., integer for long field).

elasticsearch9.exceptions.AuthenticationException: AuthenticationException(401, 'security_exception')

Invalid credentials or API key. The old elasticsearch client used basic auth; elasticsearch9 requires explicit api_key parameter format.

fix

Ensure you're passing api_key='id:api_key' or username/password via http_auth parameter.

Upgrade

Version history

9.4.1latest on PyPI · released May 26, 2026

Audit

Dependencies

elastic-transportrequiredHTTP transport layer (connection pools, retries)

certifirequiredCA bundle for TLS

urllib3optionalHTTP library

Agent activity

44 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/elastic/elasticsearch9-py ↗

homepagehttps://github.com/elastic/elasticsearch9-py ↗