{"id":5148,"library":"chromadb-client","title":"ChromaDB Client","description":"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.","status":"active","version":"1.5.7","language":"en","source_language":"en","source_url":"https://github.com/chroma-core/chroma","tags":["vector database","AI","embeddings","client","HTTP client","RAG"],"install":[{"cmd":"pip install chromadb-client","lang":"bash","label":"Install `chromadb-client`"}],"dependencies":[{"reason":"Used for managing client configuration settings.","package":"pydantic-settings","optional":false}],"imports":[{"note":"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`.","wrong":"from chromadb import Client","symbol":"HttpClient","correct":"from chromadb import HttpClient"},{"note":"Collection objects are returned by client methods after client initialization.","symbol":"Collection","correct":"collection = client.create_collection(...)"}],"quickstart":{"code":"import chromadb\nimport os\n\n# Connect to a running ChromaDB server (replace with your server's host and port)\n# For local testing, ensure a ChromaDB server is running (e.g., `chroma run --path /path/to/db`)\n# Or connect to a Chroma Cloud instance.\nclient = chromadb.HttpClient(host=os.environ.get('CHROMADB_HOST', 'localhost'), port=int(os.environ.get('CHROMADB_PORT', 8000)))\n\n# Create a collection\ncollection_name = \"my_documents\"\ntry:\n    collection = client.create_collection(name=collection_name)\n    print(f\"Collection '{collection_name}' created.\")\nexcept Exception as e:\n    print(f\"Collection '{collection_name}' might already exist or error: {e}. Attempting to get it.\")\n    collection = client.get_or_create_collection(name=collection_name)\n\n# Add documents to the collection\ncollection.add(\n    documents=[\"This is document1 about cats\", \"This is document2 about dogs\", \"A third document on artificial intelligence\"],\n    metadatas=[\n        {\"source\": \"blog\", \"category\": \"pets\"},\n        {\"source\": \"website\", \"category\": \"pets\"},\n        {\"source\": \"article\", \"category\": \"tech\"}\n    ],\n    ids=[\"doc1\", \"doc2\", \"doc3\"]\n)\nprint(f\"Added {collection.count()} documents.\")\n\n# Query the collection\nresults = collection.query(\n    query_texts=[\"tell me about animals\"],\n    n_results=2,\n    where={\"category\": \"pets\"},\n    include=[\"documents\", \"metadatas\", \"distances\"]\n)\n\nprint(\"\\nQuery Results:\")\nfor i, doc in enumerate(results['documents'][0]):\n    print(f\"  Document: {doc}\")\n    print(f\"  Metadata: {results['metadatas'][0][i]}\")\n    print(f\"  Distance: {results['distances'][0][i]}\")\n\n# Clean up (optional, for demonstration)\n# client.delete_collection(name=collection_name)\n# print(f\"Collection '{collection_name}' deleted.\")","lang":"python","description":"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."},"warnings":[{"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()`).","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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'])`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions when using library mode for the server"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions, specifically across major/minor version boundaries"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}