SDKs overview

Chroma provides Software Development Kits (SDKs) and client libraries to enable programmatic interaction with its vector database. These SDKs abstract the underlying API calls, allowing developers to integrate Chroma's functionalities directly into their applications using familiar programming languages. The primary goal of these SDKs is to simplify operations such as adding documents, creating embeddings, performing similarity searches, and managing collections within a Chroma instance, whether it's a local client, a self-hosted server, or Chroma Cloud.

The official SDKs are designed to offer a consistent interface across different deployment models, ensuring that code written for a local Chroma instance can often be adapted with minimal changes for a remote or cloud-based deployment. This approach supports a flexible development workflow, from rapid prototyping to production-scale applications. The SDKs handle aspects like connection management, data serialization, and error handling, reducing the boilerplate code required from developers.

Beyond the official offerings, the Chroma ecosystem also benefits from community-contributed libraries and integrations. These often extend Chroma's utility by providing connectors to popular AI frameworks or specialized tools, further broadening its applicability in various machine learning and artificial intelligence projects. For instance, integrations with frameworks like LangChain and LlamaIndex facilitate the creation of complex RAG (Retrieval Augmented Generation) pipelines by streamlining the interaction between large language models and the vector database.

Official SDKs by language

Chroma offers official SDKs for two primary programming languages, Python and JavaScript, reflecting their prevalence in machine learning and web development ecosystems. These SDKs are maintained by the Chroma team and are the recommended way to interact with the database.

Language Package Name Install Command Maturity
Python chromadb pip install chromadb Stable
JavaScript chromadb npm install chromadb or yarn add chromadb Stable

The Python SDK is particularly central to Chroma's ecosystem, given Python's dominance in machine learning and data science. It provides a straightforward, idiomatic interface that aligns well with existing Python-based ML workflows. The JavaScript SDK caters to developers building web applications, backend services with Node.js, or client-side applications that require direct interaction with Chroma.

Both SDKs provide methods for:

  • Client Initialization: Connecting to a local, HTTP, or Chroma Cloud instance.
  • Collection Management: Creating, getting, listing, and deleting collections.
  • Data Operations: Adding, updating, deleting, and getting documents and their associated embeddings.
  • Querying: Performing similarity searches based on embedding vectors or document metadata.

For detailed API specifications and usage examples for both Python and JavaScript, developers can refer to the Chroma API reference documentation.

Installation

Installing the Chroma SDKs is typically performed using standard package managers for each respective language.

Python SDK Installation

The Python SDK can be installed using pip, the Python package installer. It is recommended to install Chroma in a virtual environment to manage dependencies effectively.

pip install chromadb

To ensure all optional dependencies for specific features, such as different embedding functions or client types, are included, developers might install with extras:

pip install "chromadb[uvicorn,grpc,fastapi]"

This command includes dependencies for running Chroma in server mode (uvicorn, fastapi) and for gRPC communication (grpc), which might be relevant for more advanced deployments beyond the default in-memory client. For a comprehensive list of installation options, consult the Chroma getting started guide.

JavaScript SDK Installation

The JavaScript SDK can be installed using npm or yarn, the widely used package managers for Node.js projects.

# Using npm
npm install chromadb

# Using yarn
yarn add chromadb

After installation, the package can be imported into JavaScript or TypeScript projects. The JavaScript SDK supports both Node.js environments for server-side applications and modern browser environments for client-side use cases, though direct client-side interaction with a local Chroma instance is less common than server-side or cloud interaction.

Quickstart example

This quickstart demonstrates how to initialize a Chroma client, create a collection, add documents, and perform a similarity search using the Python SDK. This example uses a default in-memory client, which is suitable for local development and testing.

import chromadb

# 1. Initialize a Chroma client (in-memory for local use)
# For a persistent client, specify a path: chromadb.PersistentClient(path="./chroma_db")
# For a client connecting to a remote server: chromadb.HttpClient(host="localhost", port=8000)
client = chromadb.Client()

# 2. Create a collection
# A collection is where your documents and embeddings are stored.
# If the collection already exists, it will be retrieved.
collection_name = "my_documents"
collection = client.get_or_create_collection(name=collection_name)

# 3. Add documents and their metadata
# Chroma will automatically create embeddings for the documents if an embedding function is not specified.
collection.add(
    documents=[
        "This is a document about cats and dogs.",
        "The quick brown fox jumps over the lazy dog.",
        "Artificial intelligence is transforming industries.",
        "Machine learning models require significant data."
    ],
    metadatas=[
        {"source": "animal_facts", "author": "Alice"},
        {"source": "proverbs", "author": "Traditional"},
        {"source": "tech_news", "author": "Bob"},
        {"source": "data_science", "author": "Charlie"}
    ],
    ids=["doc1", "doc2", "doc3", "doc4"]
)
print(f"Added {collection.count()} documents to collection '{collection_name}'.")

# 4. Perform a similarity search
# Query for documents similar to the given text.
query_text = "AI and data processing"
results = collection.query(
    query_texts=[query_text],
    n_results=2,
    where={"$or": [{"author": "Bob"}, {"author": "Charlie"}]}
)

print(f"\nQuery: '{query_text}'\n")
print("Search Results:")
for i, doc in enumerate(results['documents'][0]):
    metadata = results['metadatas'][0][i]
    distance = results['distances'][0][i]
    print(f"  Document: '{doc}'")
    print(f"  Metadata: {metadata}")
    print(f"  Similarity Distance: {distance:.4f}")
    print("---------------------")

# 5. Delete the collection (optional)
# client.delete_collection(name=collection_name)
# print(f"Collection '{collection_name}' deleted.")

This example demonstrates the core workflow: client initialization, collection management, data ingestion, and querying. The where clause in the query demonstrates filtering capabilities based on document metadata, which is a common requirement in RAG and semantic search applications. For more advanced querying, including filtering by distance or using specific embedding functions, developers should consult the Chroma usage guide.

Community libraries

The Chroma ecosystem is extended by various community-contributed libraries and integrations, particularly within the broader AI and machine learning landscape. These contributions often focus on connecting Chroma with popular frameworks, enabling more complex workflows and simplifying development for specific use cases.

  • LangChain Integration: LangChain is a framework for developing applications powered by large language models. It provides a Chroma vector store integration that allows developers to use Chroma as a backend for storing and retrieving document embeddings within LangChain applications. This is crucial for building RAG systems where external knowledge needs to be retrieved and provided to an LLM. LangChain's abstraction simplifies the process of creating embeddings, adding them to Chroma, and performing similarity searches as part of a larger chain of operations.
  • LlamaIndex Integration: Similar to LangChain, LlamaIndex (formerly GPT Index) is a data framework for LLM applications. It offers a Chroma vector store module that integrates Chroma for indexing and querying unstructured data. LlamaIndex focuses on providing a central interface to connect LLMs with external data sources, and Chroma serves as a robust vector storage solution within this architecture. This integration is particularly useful for building knowledge-augmented LLM applications that require efficient data retrieval.
  • Danswer Integration: Danswer is an open-source, self-hosted Q&A platform that leverages LLMs to answer questions over internal company data. Chroma is used as a core component for storing document embeddings, facilitating semantic search over diverse data sources. This demonstrates Chroma's utility in enterprise search and knowledge management systems. Further details on Danswer's architecture can be found on its official documentation page.

These community integrations highlight Chroma's flexibility and its role as a foundational component in the rapidly evolving landscape of AI applications. Developers can often find pre-built connectors or examples for integrating Chroma with other tools in the AI stack, reducing development time and effort.