---
id: turbopuffer
version: "2.8.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# turbopuffer — The official Python library for the turbopuffer API

License: permissive · Maintenance: active · Downloads: 4.4M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 4.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

vector database python client, nearest neighbor search api, vector similarity queries, full-text search python, async vector database client, embedding storage and retrieval, ann search library, vector-search, async-ready, type-safe

[View on SkillFed](https://skillfed.io/packages/turbopuffer) · [View on PyPI](https://pypi.org/project/turbopuffer/)