ChromaDB Client

1.5.7 · active · verified Mon Apr 13

ChromaDB Client is a lightweight Python HTTP client for interacting with a running ChromaDB server. It provides a programmatic interface to store, query, and manage vector embeddings, enabling integration with AI applications for tasks like semantic search and Retrieval-Augmented Generation (RAG). The library is actively maintained with frequent releases, typically on a weekly or bi-weekly cadence.

Warnings

breaking Major breaking changes occurred around ChromaDB v1.0.0 (March 2025), which involved a rewrite in Rust and significant API restructuring. This affects method names, return types, and how clients interact with the server's various functionalities (e.g., `client.health.*`, `client.collections.*`). Ensure your client code is updated if upgrading from pre-1.0.0 versions.
Fix: Refer to the official ChromaDB migration guides for v1.0.0 for specific API changes and update your client code accordingly. This may involve changes in import patterns, client instantiation, and method calls (e.g., `client.heartbeat()` might become `client.health.heartbeat()`).
gotcha By default, `collection.query()` and `collection.get()` methods do not return embeddings to reduce payload size. If you need the embeddings, you must explicitly include them in the `include` parameter.
Fix: When calling `query()` or `get()`, add `include=['embeddings', 'documents', 'metadatas', 'distances']` to retrieve the desired information, e.g., `results = collection.query(..., include=['documents', 'embeddings'])`.
gotcha Running ChromaDB in 'library mode' (e.g., using `chromadb.PersistentClient` embedded directly within an application) with multiple worker processes (like Gunicorn) can lead to stale data. Each worker might maintain its own in-memory index, unaware of changes made by other workers.
Fix: For production deployments with multiple workers, always run ChromaDB in 'server mode' as a separate process (e.g., `chroma run --path /path/to/db`). Your `chromadb-client` instances should then connect to this central server via HTTP.
gotcha There can be cross-version incompatibilities between the `chromadb-client` and the ChromaDB server, especially with older server versions and newer clients (e.g., clients v0.5.1+ might not communicate with servers v0.5.0 or lower).
Fix: Always ensure your `chromadb-client` version is compatible with your ChromaDB server version. It's generally recommended to keep both client and server updated to the latest stable release or to match versions explicitly to avoid unexpected behavior.

Install

pip install chromadb-client Install `chromadb-client`

Imports

HttpClient
```
from chromadb import HttpClient
```
The `chromadb-client` package provides `HttpClient` for connecting to a server. `Client`, `PersistentClient`, and `EphemeralClient` are part of the full `chromadb` package, not `chromadb-client`.
Collection
```
collection = client.create_collection(...)
```
Collection objects are returned by client methods after client initialization.

Quickstart

This quickstart demonstrates how to connect to a ChromaDB server using `chromadb.HttpClient`, create a collection, add documents with metadata, and perform a similarity search. It includes an example of filtering results by metadata and ensuring embeddings are returned.

import chromadb
import os

# Connect to a running ChromaDB server (replace with your server's host and port)
# For local testing, ensure a ChromaDB server is running (e.g., `chroma run --path /path/to/db`)
# Or connect to a Chroma Cloud instance.
client = chromadb.HttpClient(host=os.environ.get('CHROMADB_HOST', 'localhost'), port=int(os.environ.get('CHROMADB_PORT', 8000)))

# Create a collection
collection_name = "my_documents"
try:
    collection = client.create_collection(name=collection_name)
    print(f"Collection '{collection_name}' created.")
except Exception as e:
    print(f"Collection '{collection_name}' might already exist or error: {e}. Attempting to get it.")
    collection = client.get_or_create_collection(name=collection_name)

# Add documents to the collection
collection.add(
    documents=["This is document1 about cats", "This is document2 about dogs", "A third document on artificial intelligence"],
    metadatas=[
        {"source": "blog", "category": "pets"},
        {"source": "website", "category": "pets"},
        {"source": "article", "category": "tech"}
    ],
    ids=["doc1", "doc2", "doc3"]
)
print(f"Added {collection.count()} documents.")

# Query the collection
results = collection.query(
    query_texts=["tell me about animals"],
    n_results=2,
    where={"category": "pets"},
    include=["documents", "metadatas", "distances"]
)

print("\nQuery Results:")
for i, doc in enumerate(results['documents'][0]):
    print(f"  Document: {doc}")
    print(f"  Metadata: {results['metadatas'][0][i]}")
    print(f"  Distance: {results['distances'][0][i]}")

# Clean up (optional, for demonstration)
# client.delete_collection(name=collection_name)
# print(f"Collection '{collection_name}' deleted.")

view raw JSON →