OpenSearch Python Client

3.1.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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

pip install opensearch-py

Common errors

error ModuleNotFoundError: No module named 'opensearchpy' ↓

cause The `opensearch-py` library is either not installed in your environment, or the import statement uses an incorrect module name.

fix

Install the library using pip install opensearch-py and ensure the import statement is from opensearchpy import OpenSearch.

error ConnectionError: ConnectionError(...) caused by: NewConnectionError(...): Failed to establish a new connection: [Errno 111] Connection refused ↓

cause The Python client cannot establish a connection to the OpenSearch cluster, often due to the cluster being down, incorrect host/port in the client configuration, or network/firewall issues.

fix

Verify that the OpenSearch cluster is running and accessible from where the client code is executed. Double-check the host and port parameters in the OpenSearch client constructor.

error AuthenticationException(401, 'Unauthorized', 'Unauthorized') ↓

cause The client attempted to connect to OpenSearch with invalid or insufficient authentication credentials (e.g., incorrect username/password, missing IAM role, or incorrect AWSV4SignerAuth configuration).

fix

Provide valid http_auth credentials or properly configure AWSV4SignerAuth when connecting to a secured OpenSearch cluster or Amazon OpenSearch Service.

error RequestError(400, 'no handler found for uri ...') ↓

cause The client is sending a malformed request, often due to an extra slash at the end of the host URL in the `OpenSearch` client configuration, leading to an incorrect URI being constructed.

fix

Ensure that the host parameter in the OpenSearch client constructor does not end with a trailing slash.

error TypeError: IndicesClient.refresh() takes 1 positional argument but 2 positional arguments (and 2 keyword-only arguments) were given ↓

cause The `IndicesClient.refresh()` method (and potentially others) in `opensearch-py` version 3.0.0 and later requires keyword arguments, but it is being called with positional arguments.

fix

Update method calls to use keyword arguments, for example, change client.indices.refresh(index_name) to client.indices.refresh(index=index_name).

Warnings

breaking Package 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

gotcha opensearch-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.

gotcha Amazon 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(...))

gotcha OpenSearch 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.

gotcha 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. ↓

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

breaking 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. ↓

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.

breaking 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. ↓

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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.78s 49.3M

3.10 slim (glibc) - - 0.55s 47M

3.11 alpine (musl) - - 1.02s 52.7M

3.11 slim (glibc) - - 0.82s 51M

3.12 alpine (musl) - - 1.13s 44.3M

3.12 slim (glibc) - - 1.12s 42M

3.13 alpine (musl) - - 1.13s 43.8M

3.13 slim (glibc) - - 1.08s 42M

3.9 alpine (musl) - - 0.68s 25.9M

3.9 slim (glibc) - - 0.59s 26M

Imports

OpenSearch

wrong

from elasticsearch import Elasticsearch  # wrong package
client = Elasticsearch(hosts=['localhost:9200'])
# opensearch-py and elasticsearch-py are different packages

correct

from opensearchpy import OpenSearch

client = OpenSearch(
    hosts=[{'host': 'localhost', 'port': 9200}],
    http_auth=('admin', 'admin'),
    use_ssl=True,
    verify_certs=False,  # dev only
    ssl_show_warn=False
)

# Index — same pattern as elasticsearch-py v7
client.index(
    index='my-index',
    body={'name': 'Alice', 'age': 30},
    id='1'
)

# Search
resp = client.search(
    index='my-index',
    body={'query': {'match': {'name': 'Alice'}}}
)

Import is 'from opensearchpy import OpenSearch' — not 'from elasticsearch import Elasticsearch'. Despite near-identical APIs, they are different packages with different auth and SSL handling.

AsyncOpenSearch

from opensearchpy import AsyncOpenSearch
import asyncio

async def main():
    client = AsyncOpenSearch(
        hosts=[{'host': 'localhost', 'port': 9200}],
        http_auth=('admin', 'admin'),
        use_ssl=False
    )
    resp = await client.search(
        index='my-index',
        body={'query': {'match_all': {}}}
    )
    await client.close()

asyncio.run(main())

AsyncOpenSearch is the async counterpart — same API as sync but all methods are coroutines. Must call await client.close() to prevent connection leaks.

Quickstart stale last tested: 2026-04-23

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'])