langchain-chroma Integration

1.1.0 · active · verified Sat Apr 11

langchain-chroma is an integration package connecting Chroma, an AI-native open-source vector database, with the LangChain framework. It enables developers to leverage Chroma for tasks such as semantic search, Retrieval-Augmented Generation (RAG), and other LLM applications. Currently at version 1.1.0, it is actively developed and maintained as part of LangChain's partner integrations, with releases often aligned with the broader LangChain ecosystem.

Warnings

breaking With the release of LangChain v0.1.0 and subsequent modularization, core components and integrations like Chroma moved to separate packages. Old import paths (e.g., `from langchain.vectorstores import Chroma`) are deprecated and will lead to `ImportError` or unexpected behavior.
Fix: Update imports to use the dedicated `langchain_chroma` package: `from langchain_chroma import Chroma`. Similarly, `Document` moved to `langchain_core.documents`.
gotcha When connecting to a remote ChromaDB server, ensure the `chromadb` client version installed (as a dependency of `langchain-chroma`) is compatible with the server's version. Incompatible client/server versions, especially with major updates to ChromaDB (e.g., v1.x based on Rust), can lead to connection errors or unexpected behavior.
Fix: Consult ChromaDB and `langchain-chroma` documentation for recommended `chromadb` client versions. Upgrade or downgrade `chromadb` as necessary to match your server environment: `pip install chromadb==X.Y.Z`.
gotcha Earlier versions of `langchain-chroma` (e.g., 0.2.2) had strict `numpy` dependency constraints (`numpy>=1.26.2,<2.0.0`) which could conflict with other packages requiring newer `numpy` versions (`>=2.0.0`), causing installation failures.
Fix: Upgrade `langchain-chroma` to the latest version (`1.1.0` or higher), as dependency constraints are typically relaxed or updated in newer releases to improve compatibility. If conflicts persist, try installing `numpy` first with a broad range, then `langchain-chroma`.
gotcha When using `update_documents` with Chroma, some older versions might have expected explicit metadata, even if optional, leading to `ValueError` if an empty list was internally generated instead of `None`.
Fix: Ensure `Document` objects passed to `update_documents` either have a valid `metadata` dictionary or explicitly set `metadata=None` if no metadata is desired. Always test `update_documents` carefully with and without metadata in your specific `langchain-chroma` version.

Install

pip install -qU langchain-chroma chromadb langchain-openai langchain-text-splitters Install core and common dependencies

Imports

Chroma
```
from langchain_chroma import Chroma
```
OpenAIEmbeddings
```
from langchain_openai import OpenAIEmbeddings
```
Used for generating embeddings, commonly paired with Chroma.
RecursiveCharacterTextSplitter
```
from langchain_text_splitters import RecursiveCharacterTextSplitter
```
Used for processing documents before adding them to the vector store.
Document
```
from langchain_core.documents import Document
```
Post LangChain v0.1.0, Document moved to langchain_core.documents.

Quickstart

This quickstart demonstrates how to set up a Chroma vector store with LangChain, using OpenAI embeddings. It covers document loading, splitting, vector store initialization, and performing a similarity search. For local persistence, uncomment the `persist_directory` argument during Chroma initialization.

import os
from langchain_chroma import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter

# Set your OpenAI API key from environment variables
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "YOUR_OPENAI_API_KEY")

# Sample documents
raw_documents = [
    "The quick brown fox jumps over the lazy dog.",
    "The cat sat on the mat.",
    "Chroma is an open-source vector database.",
    "LangChain provides tools for building LLM applications.",
    "RAG combines retrieval and generation for better answers."
]

# 1. Split documents (optional but good practice for RAG)
text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
documents = [Document(page_content=d) for d in raw_documents]
split_documents = text_splitter.split_documents(documents)

# 2. Initialize embeddings
embeddings = OpenAIEmbeddings()

# 3. Create a Chroma vector store (in-memory for this example)
# For persistence, pass a 'persist_directory' argument: persist_directory="./chroma_db"
vector_store = Chroma(
    collection_name="my_documents_collection",
    embedding_function=embeddings,
)

# Add documents to the vector store
vector_store.add_documents(split_documents)

# 4. Perform a similarity search
query = "What is Chroma?"
results = vector_store.similarity_search(query, k=1)

print(f"Query: {query}")
for doc in results:
    print(f"- Found document: {doc.page_content}")

view raw JSON →