{"id":44825,"library":"elasticsearch9","title":"Elasticsearch Python Client","description":"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.","status":"active","version":"9.4.1","language":"python","source_language":"en","source_url":"https://github.com/elastic/elasticsearch9-py","tags":["elasticsearch","search","client"],"install":[{"cmd":"pip install elasticsearch9","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"HTTP transport layer (connection pools, retries)","package":"elastic-transport","optional":false},{"reason":"CA bundle for TLS","package":"certifi","optional":false},{"reason":"HTTP library","package":"urllib3","optional":true}],"imports":[{"note":"elasticsearch is the deprecated client; always use elasticsearch9","wrong":"from elasticsearch import Elasticsearch","symbol":"Elasticsearch","correct":"from elasticsearch9 import Elasticsearch"},{"note":"helpers are now under elasticsearch9, not elasticsearch","wrong":"from elasticsearch.helpers import scan","symbol":"helpers","correct":"from elasticsearch9 import helpers"}],"quickstart":{"code":"import os\nfrom elasticsearch9 import Elasticsearch\n\nclient = Elasticsearch(\n    os.environ.get('ELASTICSEARCH_URL', 'http://localhost:9200'),\n    api_key=os.environ.get('ELASTICSEARCH_API_KEY', ''),\n    verify_certs=False  # For dev only\n)\nprint(client.info())","lang":"python","description":"Create a client and ping the cluster. Uses environment variables for credentials."},"warnings":[{"fix":"Always use 'from elasticsearch9 import Elasticsearch'","message":"All modules and classes are under 'elasticsearch9' namespace. Importing from 'elasticsearch' will use the old deprecated client (v7/8) and break in v9.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Elasticsearch(..., verify_certs=False) or configure ssl_assert_fingerprint","message":"SSL 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.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"from elastic_transport import Sniffer","message":"The '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.","severity":"deprecated","affected_versions":">=9.0.0"},{"fix":"Elasticsearch(..., api_key='id:api_key')","message":"API 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.","severity":"gotcha","affected_versions":">=9.0.0"},{"fix":"Access results via response['hits']['hits'] and extract fields from '_source'","message":"Elasticsearch 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.","severity":"breaking","affected_versions":">=9.0.0"}],"env_vars":null,"search_vec":"'3.10':34 '9':13 'api':23 'cadenc':40 'client':3,9,43 'connect':27 'elast':37 'elasticsearch':1,11,21,41 'error':30 'handl':24,31 'level':7 'low':6 'low-level':5 'offici':4 'pool':28 'provid':15 'python':2,8,33 'quarter':39 'releas':35 'request':25 'requir':32 'rest':22 'search':42 'serial':26 'thin':17 'version':12 'wrapper':18 'x':14","created_at":"2026-06-07T12:52:01.703882+00:00","updated_at":"2026-06-07T12:52:01.703882+00:00","problems":[{"fix":"Uninstall both: pip uninstall elasticsearch elasticsearch9; then reinstall: pip install elasticsearch9","cause":"You installed elasticsearch9 but tried importing from 'elasticsearch' (the old package).","error":"ModuleNotFoundError: No module named 'elasticsearch'"},{"fix":"Add verify_certs=False to Elasticsearch constructor, or set SSL_CERT_FILE env variable.","cause":"Default SSL verification fails against self-signed certificates.","error":"elasticsearch9.exceptions.ConnectionError: ConnectionError(<urllib3.connection.HTTPSConnection object ...) caused by: SSLError([SSL: CERTIFICATE_VERIFY_FAILED]"},{"fix":"Create the index first: client.indices.create(index='my-index', ignore=400)","cause":"Trying to read/write to a non-existent index. Common when index name is misspelled or auto-creation is disabled.","error":"elasticsearch9.exceptions.NotFoundError: NotFoundError(404, 'index_not_found_exception')"},{"fix":"Update the mapping or ensure the field value matches the expected type (e.g., integer for long field).","cause":"Sending a document with a field type that conflicts with the mapping.","error":"elasticsearch9.exceptions.RequestError: RequestError(400, 'mapper_parsing_exception', 'failed to parse field')"},{"fix":"Ensure you're passing api_key='id:api_key' or username/password via http_auth parameter.","cause":"Invalid credentials or API key. The old elasticsearch client used basic auth; elasticsearch9 requires explicit api_key parameter format.","error":"elasticsearch9.exceptions.AuthenticationException: AuthenticationException(401, 'security_exception')"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/elastic/elasticsearch9-py","github":"https://github.com/elastic/elasticsearch9-py","docs":null,"changelog":null,"pypi":null,"npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["search","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":null}}