typesense

library2.0.0pypypi✓ verified 27d ago

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.

database http-networking

pip install typesense

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · TYPESENSE

typesense

databasepythonv2.0.0

Install

2.6s avg

Import

320ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.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.95 runs

installs and imports cleanly · install 0.0s · import 0.338s · 23.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.302s · 24MB

22MB installed

● package 22MB

Code

Verified usage

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

Client

✓ from typesense import Client

✗ import typesense

AsyncClient

✓ from typesense import AsyncClient

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

Debug

Known issues

gotchaClient 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': '...'}

affects: all

gotchaTypesense 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'.

affects: all

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

affects: all

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

fix

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

affects: all

gotchaAsyncClient (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.

affects: >= 2.0

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

affects: all

Upgrade

Version history

2.0.0latest on PyPI · released Feb 16, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node