{"id":169,"library":"opensearch-py","title":"OpenSearch Python Client","description":"Official Python client for OpenSearch — AWS's Apache 2.0 fork of Elasticsearch 7.10. Current version: 3.1.0 (Mar 2026). API is nearly identical to elasticsearch-py v7 but NOT interchangeable — different package, different import. OpenSearch 1.x deprecated May 2025. v3.0 client released alongside OpenSearch 3.0. Major footgun: developers import elasticsearch instead of opensearch_py by mistake. Also compatible with Amazon OpenSearch Service (AWS managed).","status":"active","version":"3.1.0","language":"python","source_language":"en","source_url":"https://github.com/opensearch-project/opensearch-py","tags":["opensearch","python","search","aws","elasticsearch-fork"],"install":[{"cmd":"pip install opensearch-py","lang":"bash","label":"Python (sync + async)"}],"dependencies":[{"reason":"Required. Installed automatically.","package":"urllib3","optional":false}],"imports":[{"wrong":"from opensearchpy import OpenSearch","symbol":"OpenSearch","correct":"from opensearchpy import OpenSearch"}],"quickstart":{"code":"# pip install opensearch-py\nfrom opensearchpy import OpenSearch\n\nclient = OpenSearch(\n    hosts=[{'host': 'localhost', 'port': 9200}],\n    http_auth=('admin', 'admin'),\n    use_ssl=False\n)\n\n# Create index\nclient.indices.create(\n    index='products',\n    body={\n        'mappings': {\n            'properties': {\n                'name': {'type': 'text'},\n                'price': {'type': 'float'}\n            }\n        }\n    }\n)\n\n# Index document\nclient.index(index='products', id='1', body={'name': 'Widget', 'price': 9.99})\n\n# Search\nresp = client.search(\n    index='products',\n    body={'query': {'match': {'name': 'Widget'}}}\n)\nfor hit in resp['hits']['hits']:\n    print(hit['_source'])","lang":"python","description":"Minimal opensearch-py connection and CRUD."},"warnings":[{"fix":"pip install opensearch-py; from opensearchpy import OpenSearch","message":"Package name is 'opensearch-py' but import is 'from opensearchpy import OpenSearch' (no hyphen). pip install opensearch-py; import opensearchpy.","severity":"breaking","affected_versions":"all"},{"fix":"Use opensearch-py for OpenSearch/Amazon OpenSearch Service. Use elasticsearch for Elasticsearch.","message":"opensearch-py and elasticsearch-py have near-identical APIs but are NOT interchangeable. Different packages, different auth patterns, different SSL defaults. Cannot swap imports.","severity":"gotcha","affected_versions":"all"},{"fix":"from requests_aws4auth import AWS4Auth; client = OpenSearch(http_auth=AWS4Auth(...))","message":"Amazon OpenSearch Service (AWS managed) requires AWS SigV4 auth — not basic_auth. Use opensearch-py with requests-aws4auth or boto3 credentials.","severity":"gotcha","affected_versions":"all"},{"fix":"Target OpenSearch 2.x or 3.x for new projects.","message":"OpenSearch 1.x deprecated May 2025. Amazon OpenSearch Service still supports 1.x and 2.x but new projects should target 2.x+.","severity":"gotcha","affected_versions":"all"},{"fix":"client.search(index='my-index', body={'query': {...}}) — body= is correct for opensearch-py.","message":"Unlike elasticsearch-py v8+, opensearch-py still uses the body= parameter pattern (elasticsearch v7 style). Don't apply elasticsearch v8 named-param migration to opensearch-py.","severity":"gotcha","affected_versions":"all"},{"fix":"Verify that your OpenSearch instance is running and listening on the correct host and port. Check network connectivity, host address, port number, and any firewall rules that might be blocking the connection from the client to the OpenSearch server.","message":"ConnectionRefusedError: OpenSearch client failed to connect to the server. This indicates that the OpenSearch instance is not running, is not accessible at the specified host/port, or a firewall is blocking the connection.","severity":"breaking","affected_versions":"all"},{"fix":"Verify that the OpenSearch service is running on the specified host and port. Check your client configuration for the correct host and port. Ensure no firewall rules or network configurations are blocking the connection.","message":"Connection refused: The OpenSearch service is not running or is not accessible at the specified host and port (e.g., `localhost:9200`). Ensure the OpenSearch cluster is running and network accessible from where the client is executed.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"search_vec":"'1':39 '2.0':12 '2025':43 '2026':21 '3.0':49 '3.1.0':19 '7.10':16 'alongsid':47 'also':61 'amazon':64 'apach':11 'api':22 'aw':9,67,72 'client':3,6,45 'compat':62 'current':17 'deprec':41 'develop':52 'differ':34,36 'elasticsearch':15,28,54,74 'elasticsearch-fork':73 'elasticsearch-pi':27 'footgun':51 'fork':13,75 'ident':25 'import':37,53 'instead':55 'interchang':33 'major':50 'manag':68 'mar':20 'may':42 'mistak':60 'near':24 'offici':4 'opensearch':1,8,38,48,57,65,69 'packag':35 'py':29,58 'python':2,5,70 'releas':46 'search':71 'servic':66 'v3.0':44 'v7':30 'version':18 'x':40","created_at":"2026-03-24T19:07:19.927853+00:00","updated_at":"2026-04-16T17:37:33.802142+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"3.2.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://opensearch.org","github":"https://github.com/opensearch-project/opensearch-py","docs":"https://opensearch.org/docs/clients/python","changelog":null,"pypi":"https://pypi.org/project/opensearch-py/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","aws"],"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":"verified"}}