Install & Compatibility
Where this runs
tested against v1.1.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
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 28.8s · import 4.178s · 535MB
506MB installed
● package 506MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✗ from langchain.docstore.document import Document
Post LangChain v0.1.0, Document moved to langchain_core.documents.
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}")
Debug
Known issues
breakingWith 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.fixUpdate imports to use the dedicated `langchain_chroma` package: `from langchain_chroma import Chroma`. Similarly, `Document` moved to `langchain_core.documents`.
affects: >=0.1.0
gotchaWhen 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.fixConsult 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`.
affects: All versions, particularly with `chromadb` server 1.x
gotchaEarlier 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.fixUpgrade `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`.
affects: 0.2.2 and potentially other older minor versions
gotchaWhen 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`.fixEnsure `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.
affects: Older versions like 0.2.2 (reported in August 2024), possibly resolved in later updates.
Upgrade
Version history
1.1.0latest on PyPI · released Dec 12, 2025
Audit
Dependencies
chromadbrequiredRequired for ChromaDB client functionality to interact with the Chroma vector database.
langchain-corerequiredProvides foundational components and abstractions used across the LangChain ecosystem.
langchain-openaioptionalCommonly used for OpenAI embedding models, essential for most vector store operations.
langchain-text-splittersoptionalProvides utilities for splitting documents into chunks, a common prerequisite for RAG applications.