turbopuffer

What it is and what it does

turbopuffer is the official Python client for the turbopuffer vector database API. It wraps HTTP endpoints with type-safe, auto-completing request and response objects built on pydantic, and offers both synchronous and asynchronous clients powered by httpx. The library is generated by Stainless and supports Python 3.9 and later.

You use it to query vectors by nearest-neighbor search (ANN), perform full-text search on indexed attributes, upsert and manage vector embeddings in namespaces, and handle pagination across result sets. Both sync and async clients have identical functionality; the async variant can optionally use aiohttp as its HTTP backend for improved concurrency. Error handling distinguishes between connection failures, rate limits, and API status errors.

Use it for:

• Build a semantic search feature by querying nearest neighbors to an embedding vector.
• Implement hybrid search combining vector similarity with full-text BM25 ranking.
• Manage and upsert large batches of embeddings into isolated namespaces.
• Integrate vector search into async Python applications without blocking.
• Prototype or deploy AI/ML applications that rely on vector similarity at query time.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides a Python client library for the turbopuffer vector database API, with both synchronous and asynchronous interfaces for querying and managing vector embeddings and full-text search.

Yes. The package is actively maintained, has no known vulnerabilities, installs with low friction, uses a permissive MIT license, and provides a clean, type-safe interface to a vector database service. Install it if you need to query or manage vector embeddings via the turbopuffer API from Python.

Install

turbopuffer on PyPI

pip install turbopuffer

uv add turbopuffer

poetry add turbopuffer

Installing turbopuffer

Before you install

Low friction installation with a pure Python wheel. Active maintenance—last commit 2026-08-12, release 10 days old. Depends on httpx, pydantic, and several async/serialization utilities; all are stable, widely-used packages.

License in practice

MIT license (permissive). You can use, modify, and distribute this package freely in commercial or private projects with minimal restrictions.

Quickstart

pip install turbopuffer

import os
from turbopuffer import Turbopuffer

tpuf = Turbopuffer(
    region="gcp-us-central1",
    api_key=os.environ.get("TURBOPUFFER_API_KEY"),
)
ns = tpuf.namespace("example")
vector_result = ns.query(
    rank_by=("vector", "ANN", [0.1, 0.2]),
    top_k=10,
)
print(vector_result.rows)

Requires Python 3.9 or later. Requires a turbopuffer API key (set via TURBOPUFFER_API_KEY environment variable or passed to the client).

Verify before relying

• Whether the aiohttp extra (turbopuffer[aiohttp]) is recommended for production async workloads or optional for most use cases.
• Performance characteristics and latency expectations for vector queries at scale.
• Rate limiting and quota behavior when exceeding API limits.

Package facts

Evidence: turbopuffer-2.8.0-py3-none-any.whl

Tags

More Python Modules packages