opensearch-py

library3.1.0pypypi✓ verified 51d ago

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).

database aws

pip install opensearch-py

github ↗package ↗homepage ↗docs ↗

Install & Compatibility

Where this runs

tested against v3.2.0 · 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

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.950s · 49.5MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 3.5s · import 0.843s · 47MB

43MB installed

● package 43MB

Code

Verified usage

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

OpenSearch

✓ from opensearchpy import OpenSearch

✗ from opensearchpy import OpenSearch

Minimal opensearch-py connection and CRUD.

# pip install opensearch-py from opensearchpy import OpenSearch client = OpenSearch( hosts=[{'host': 'localhost', 'port': 9200}], http_auth=('admin', 'admin'), use_ssl=False ) # Create index client.indices.create( index='products', body={ 'mappings': { 'properties': { 'name': {'type': 'text'}, 'price': {'type': 'float'} } } } ) # Index document client.index(index='products', id='1', body={'name': 'Widget', 'price': 9.99}) # Search resp = client.search( index='products', body={'query': {'match': {'name': 'Widget'}}} ) for hit in resp['hits']['hits']: print(hit['_source'])

Debug

Known issues

breakingPackage name is 'opensearch-py' but import is 'from opensearchpy import OpenSearch' (no hyphen). pip install opensearch-py; import opensearchpy.

fix

pip install opensearch-py; from opensearchpy import OpenSearch

affects: all

gotchaopensearch-py and elasticsearch-py have near-identical APIs but are NOT interchangeable. Different packages, different auth patterns, different SSL defaults. Cannot swap imports.

fix

Use opensearch-py for OpenSearch/Amazon OpenSearch Service. Use elasticsearch for Elasticsearch.

affects: all

gotchaAmazon OpenSearch Service (AWS managed) requires AWS SigV4 auth — not basic_auth. Use opensearch-py with requests-aws4auth or boto3 credentials.

fix

from requests_aws4auth import AWS4Auth; client = OpenSearch(http_auth=AWS4Auth(...))

affects: all

gotchaOpenSearch 1.x deprecated May 2025. Amazon OpenSearch Service still supports 1.x and 2.x but new projects should target 2.x+.

fix

Target OpenSearch 2.x or 3.x for new projects.

affects: all

gotchaUnlike 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.

fix

client.search(index='my-index', body={'query': {...}}) — body= is correct for opensearch-py.

affects: all

breakingConnectionRefusedError: 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.

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.

affects: all

breakingConnection 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.

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.

affects: all

Upgrade

Version history

3.2.0latest on PyPI

Audit

Dependencies

urllib3requiredRequired. Installed automatically.

Agent activity

35 hits · last 30 days

node

seranking-bot

bytedance

ahrefsbot