Typesense Python Client

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

Official Python client for Typesense — open source typo-tolerant search engine, alternative to Algolia/Elasticsearch. Current version: 2.0.0 (Mar 2026). v2.0 added AsyncClient. Client takes a config dict with 'nodes' list — not a URL string. Typesense Cloud uses port 443 and HTTPS. Self-hosted uses port 8108 and HTTP by default.

pip install typesense

Common errors

error ModuleNotFoundError: No module named 'typesense' ↓

cause The 'typesense' Python client library has not been installed in the current development environment.

fix

pip install typesense

error KeyError: 'nodes' ↓

cause The `typesense.Client` constructor requires a configuration dictionary that includes a 'nodes' key, which is a list of server node configurations.

fix

client = typesense.Client({ 'nodes': [{ 'host': 'localhost', 'port': '8108', 'protocol': 'http' # Use 'https' for Typesense Cloud }], 'api_key': 'your_api_key' })

error typesense.exceptions.TypesenseClientError: Connection refused ↓

cause The Typesense server is either not running, not accessible at the specified host and port, or a firewall is blocking the connection.

fix

Verify the Typesense server is running and that the host, port, and protocol in your client configuration accurately match the server's address and access settings.

error TypeError: 'coroutine' object is not subscriptable ↓

cause Methods of `typesense.AsyncClient` return asynchronous coroutine objects that must be awaited to execute and yield their results, but the `await` keyword was omitted.

fix

async def my_async_function(): # ... async client setup ... schema = {'name': 'my_collection', 'fields': [{'name': 'id', 'type': 'string'}]} collection = await async_client.collections.create(schema) # Prepend 'await' print(collection['name'])

error typesense.exceptions.TypesenseClientError: [401] Unauthorized ↓

cause The API key provided in the `typesense.Client` configuration is either incorrect or lacks the necessary permissions for the requested operation.

fix

Update the api_key in your typesense.Client configuration to a valid Typesense API key with the required permissions.

Warnings

gotcha Client config requires 'nodes' as a list — not a URL string or flat host/port keys. Passing a URL string raises TypeError. ↓

fix Always: {'nodes': [{'host': '...', 'port': '8108', 'protocol': 'http'}], 'api_key': '...'}

gotcha Typesense Cloud uses port 443 and protocol 'https'. Self-hosted defaults to port 8108 and 'http'. Mixing these up causes connection errors. ↓

fix Cloud: port='443', protocol='https'. Self-hosted: port='8108', protocol='http'.

gotcha Collection schema is required before indexing — Typesense is schema-enforced unlike Elasticsearch. Indexing without creating collection first raises ObjectNotFound. ↓

fix Always call client.collections.create({...}) before indexing documents.

gotcha document 'id' field must be a string — not an integer. Passing int raises validation error. ↓

fix Always stringify IDs: {'id': str(record_id), ...}

gotcha AsyncClient (v2.0) requires await client.api_call.aclose() to close connections. Omitting this leaks HTTP connections. ↓

fix await client.api_call.aclose() when done, or use try/finally.

gotcha Client version should match Typesense server version. Python client v2.0 targets Typesense server v26+. Check compatibility matrix. ↓

fix See https://github.com/typesense/typesense-python for compatibility matrix.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.31s 23.3M

3.10 slim (glibc) - - 0.23s 24M

3.11 alpine (musl) - - 0.46s 25.6M

3.11 slim (glibc) - - 0.36s 26M

3.12 alpine (musl) - - 0.36s 17.4M

3.12 slim (glibc) - - 0.38s 18M

3.13 alpine (musl) - - 0.35s 17.0M

3.13 slim (glibc) - - 0.35s 18M

3.9 alpine (musl) - - 0.29s 22.6M

3.9 slim (glibc) - - 0.27s 23M

Imports

Client (sync)

wrong

import typesense
# Wrong: URL string instead of config dict
client = typesense.Client('http://localhost:8108')
# Wrong: no nodes list
client = typesense.Client({'api_key': 'key', 'host': 'localhost'})

correct

import typesense

client = typesense.Client({
    'nodes': [{
        'host': 'localhost',
        'port': '8108',
        'protocol': 'http'
    }],
    'api_key': 'your-api-key',
    'connection_timeout_seconds': 2
})

# Create collection
client.collections.create({
    'name': 'products',
    'fields': [
        {'name': 'name', 'type': 'string'},
        {'name': 'price', 'type': 'float'}
    ],
    'default_sorting_field': 'price'
})

# Index document
client.collections['products'].documents.create({
    'id': '1',
    'name': 'Widget',
    'price': 9.99
})

# Search
result = client.collections['products'].documents.search({
    'q': 'widget',
    'query_by': 'name'
})

Client takes a config dict with a 'nodes' list — not a URL string. nodes is always a list even for single-node setups.

AsyncClient (v2.0+)

import typesense
import asyncio

async def main():
    client = typesense.AsyncClient({
        'nodes': [{
            'host': 'localhost',
            'port': '8108',
            'protocol': 'http'
        }],
        'api_key': 'your-api-key',
        'connection_timeout_seconds': 2
    })
    result = await client.collections.retrieve()
    await client.api_call.aclose()  # must close
    return result

asyncio.run(main())

AsyncClient added in v2.0. Must call await client.api_call.aclose() when done to close HTTP connections.

Quickstart stale last tested: 2026-04-23

Typesense Python client — collection creation, indexing, and search.

# pip install typesense
import typesense

# Self-hosted
client = typesense.Client({
    'nodes': [{'host': 'localhost', 'port': '8108', 'protocol': 'http'}],
    'api_key': 'your-api-key',
    'connection_timeout_seconds': 2
})

# Typesense Cloud
# client = typesense.Client({
#     'nodes': [{'host': 'xxx.a1.typesense.net', 'port': '443', 'protocol': 'https'}],
#     'api_key': 'your-cloud-api-key',
#     'connection_timeout_seconds': 2
# })

# Create collection with schema
client.collections.create({
    'name': 'books',
    'fields': [
        {'name': 'title', 'type': 'string'},
        {'name': 'author', 'type': 'string', 'facet': True},
        {'name': 'year', 'type': 'int32'}
    ]
})

# Index
client.collections['books'].documents.create({
    'id': '1', 'title': 'Dune', 'author': 'Herbert', 'year': 1965
})

# Search
result = client.collections['books'].documents.search({
    'q': 'dune',
    'query_by': 'title,author'
})
print(result['hits'])