Registry /
llm-agents / llama-index-vector-stores-chroma
Install & Compatibility
Where this runs
tested against v0.5.5 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 33.2s · import 6.893s · 579MB
553MB installed
● package 553MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChromaVectorStore
✓ from llama_index.vector_stores.chroma import ChromaVectorStore
✗ from llama_index.vector_stores import ChromaVectorStore
The `vector_stores` sub-package is now an integration, requiring the full path. Older LlamaIndex versions (pre-v0.10) might have used the shorter import.
This quickstart demonstrates how to set up `ChromaVectorStore` with LlamaIndex using an in-memory ChromaDB client. It includes loading documents, indexing them with the specified vector store, and performing a basic query. It uses `HuggingFaceEmbedding` for local embeddings and sets `Settings.embed_model` and `Settings.llm` (implicitly for query engine) for modern LlamaIndex configurations.
import os
import chromadb
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, StorageContext, Settings
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.vector_stores.chroma import ChromaVectorStore
# --- Configuration ---
# For a fully local setup, use a local LLM and Embedding model.
# If using OpenAI, uncomment and set API key:
# from llama_index.llms.openai import OpenAI
# os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "")
# Settings.llm = OpenAI()
# Using a local embedding model for demonstration without external API keys
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")
# 1. Create a Chroma client and collection
# Use EphemeralClient for in-memory, or PersistentClient for disk storage
chroma_client = chromadb.EphemeralClient() # For persistent storage: chromadb.PersistentClient(path="./chroma_db")
chroma_collection = chroma_client.create_collection("my_documents_collection")
# 2. Set up the ChromaVectorStore
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
# 3. Create a StorageContext and link the vector store
storage_context = StorageContext.from_defaults(vector_store=vector_store)
# 4. Load documents (e.g., from a 'data' directory)
# Create a dummy file for demonstration if 'data' doesn't exist
if not os.path.exists("data"): os.makedirs("data")
with open("data/example.txt", "w") as f:
f.write("The quick brown fox jumps over the lazy dog. LlamaIndex is great.")
documents = SimpleDirectoryReader("data").load_data()
# 5. Create a VectorStoreIndex from documents
# embed_model is implicitly used from Settings.embed_model
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
# 6. Query the index
query_engine = index.as_query_engine()
response = query_engine.query("What is LlamaIndex?")
print(response.response)
Debug
Known issues
breakingWith LlamaIndex v0.10 and later, the library underwent a major packaging refactor. Integration packages like `llama-index-vector-stores-chroma` are now separate from `llama-index-core`. This changes import paths and requires explicit installation of integration packages.fixEnsure `llama-index-vector-stores-chroma` is installed separately and update import statements from `from llama_index.vector_stores.chroma import ChromaVectorStore` instead of `from llama_index.vector_stores import ChromaVectorStore`. Also, check if `llama-index-core` is installed.
affects: >=0.10.0
gotchaThe `chromadb` package is a peer dependency of `llama-index-vector-stores-chroma` and must be installed separately. Failing to install `chromadb` will result in `ModuleNotFoundError` even if `llama-index-vector-stores-chroma` is installed.fixAlways install `chromadb` alongside `llama-index-vector-stores-chroma`: `pip install llama-index-vector-stores-chroma chromadb`.
affects: All
gotchaVersion conflicts, particularly involving `onnxruntime`, can occur between `llama-index-vector-stores-chroma` and other installed packages (especially `chromadb`). This often manifests during installation.fixTry to loosen version constraints in your `requirements.txt` or `pyproject.toml`. If using `conda`, installing `onnxruntime` via `conda-forge` *before* pip installing `llama-index-vector-stores-chroma` has been reported as a workaround: `conda install -c conda-forge onnxruntime`.
affects: All
deprecatedOlder LlamaIndex concepts like `GPTSimpleVectorIndex`, `GPTVectorStoreIndex`, `ServiceContext`, and `LLMPredictor` have been deprecated or renamed.fixMigrate to `VectorStoreIndex`, `Settings`, and direct LLM/embedding model configuration. Refer to the LlamaIndex v0.10 migration guide.
affects: >=0.10.0
gotchaCalling the `get_nodes` function of `ChromaVectorStore` with an empty list (`[]`) for `node_ids` can raise a `Expected IDs to be a non-empty list` error due to validation changes in `chromadb`.fixEnsure `node_ids` passed to `get_nodes` is never an empty list. If you intend to retrieve all nodes matching filters without specific IDs, adjust your logic to avoid passing an empty `node_ids` list.
affects: ChromaDB >= 0.4.0 (affecting llama-index-vector-stores-chroma versions that rely on it)
Upgrade
Version history
0.5.5latest on PyPI · released Dec 30, 2025
Audit
Dependencies
chromadbrequiredRequired for ChromaDB functionality; often a hidden dependency that causes ModuleNotFoundErrors if not installed separately.
llama-index-corerequiredStarting with LlamaIndex v0.10+, core functionalities are in `llama-index-core`. This package depends on it.