Install & Compatibility
Where this runs
tested against v2.9.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.384s · 42.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.1s · import 1.198s · 44MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
turbopuffer
✓ import turbopuffer as tp
This quickstart initializes the Turbopuffer client, creates or retrieves a namespace, upserts sample vectors with metadata, and then performs a simple query. Ensure the `TURBOPUFFER_API_KEY` environment variable is set for authentication.
import turbopuffer as tp
import os
# Ensure your API key is set as an environment variable (TURBOPUFFER_API_KEY)
api_key = os.environ.get('TURBOPUFFER_API_KEY', 'YOUR_API_KEY')
if not api_key or api_key == 'YOUR_API_KEY':
print("Warning: TURBOPUFFER_API_KEY environment variable not set. Using dummy key.")
tp.init(api_key=api_key)
namespace_name = "my_first_namespace"
# Creating a namespace (idempotent operation)
# You might get a 409 Conflict if it already exists, which is fine.
# The library's methods generally handle existing resources gracefully.
# For example, create_namespace will return the existing namespace if it already exists
# instead of raising an error.
try:
namespace = tp.VectorDatabase.create_namespace(namespace_name)
print(f"Namespace '{namespace_name}' created or retrieved successfully.")
except tp.APIStatusError as e:
if e.status_code == 409:
print(f"Namespace '{namespace_name}' already exists. Retrieving it.")
namespace = tp.VectorDatabase.get_namespace(namespace_name)
else:
raise
# Upserting data
vectors = [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]
ids = [1, 2]
metadata = [{'text': 'hello'}, {'text': 'world'}]
namespace.upsert(ids=ids, vectors=vectors, metadata=metadata)
print("Vectors upserted.")
# Querying data
query_vector = [0.11, 0.22, 0.33]
results = namespace.query(vector=query_vector, top_k=1)
print(f"Query results: {results.vectors[0]} with metadata {results.metadata[0]}.")
Errors
Common errors & fixes
turbopuffer.api.APIError: API call failed with status 401: Unauthorized
The Turbopuffer API key is missing, incorrect, or expired, preventing successful authentication with the service.
fixSet the `TURBOPUFFER_API_KEY` environment variable or explicitly provide the key using `turbopuffer.set_api_key('YOUR_API_KEY')` before making any API calls. ModuleNotFoundError: No module named 'turbopuffer'
The `turbopuffer` Python client library has not been installed in the current Python environment.
fixInstall the library using pip: `pip install turbopuffer`
ValueError: Expected ids, vectors, and metadata to be lists of the same length.
During an upsert operation, the provided lists for `ids`, `vectors`, or `metadata` (if included) do not have an equal number of elements.
fixEnsure that all input lists (`ids`, `vectors`, `metadata`) passed to `namespace.upsert()` have the exact same number of items.
AttributeError: module 'turbopuffer' has no attribute 'upsert'
Methods like `upsert()` or `query()` must be called on a specific `VectorDatabase.Namespace` object, not directly on the `turbopuffer` module.
fixFirst, obtain a namespace object (e.g., `ns = turbopuffer.VectorDatabase.get_or_create_namespace('my_namespace')`), then call the desired method on that object (e.g., `ns.upsert(...)`). turbopuffer.api.APIError: API call failed with status 404: Not Found
The specified Turbopuffer namespace either does not exist, the API key lacks access to it, or its name is misspelled.
fixVerify the namespace name for correctness, ensure the namespace has been created (e.g., using `turbopuffer.VectorDatabase.get_or_create_namespace()`), and confirm the API key has appropriate permissions.
Upgrade
Version history
2.9.0latest on PyPI · released Aug 21, 2026
Audit
Dependencies
No dependency data recorded yet.