{"id":7378,"library":"llama-index-vector-stores-chroma","title":"Chroma Vector Store for LlamaIndex","description":"The `llama-index-vector-stores-chroma` library provides an integration between LlamaIndex and ChromaDB, an open-source vector database. It enables users to store and query document embeddings within a ChromaDB collection, supporting various modes like in-memory, persistent, and client-server setups. This integration is actively maintained, with the current version being `0.5.5`, and typically follows the continuous release cadence of the broader LlamaIndex ecosystem for new features and bug fixes.","status":"active","version":"0.5.5","language":"en","source_language":"en","source_url":"https://github.com/run-llama/llama_index/tree/main/llama-index-integrations/vector_stores/llama-index-vector-stores-chroma","tags":["llama-index","chromadb","vector-store","rag","embeddings","llm-integration"],"install":[{"cmd":"pip install llama-index-vector-stores-chroma chromadb","lang":"bash","label":"Recommended Installation"}],"dependencies":[{"reason":"Required for ChromaDB functionality; often a hidden dependency that causes ModuleNotFoundErrors if not installed separately.","package":"chromadb"},{"reason":"Starting with LlamaIndex v0.10+, core functionalities are in `llama-index-core`. This package depends on it.","package":"llama-index-core"}],"imports":[{"note":"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.","wrong":"from llama_index.vector_stores import ChromaVectorStore","symbol":"ChromaVectorStore","correct":"from llama_index.vector_stores.chroma import ChromaVectorStore"}],"quickstart":{"code":"import os\nimport chromadb\nfrom llama_index.core import VectorStoreIndex, SimpleDirectoryReader, StorageContext, Settings\nfrom llama_index.embeddings.huggingface import HuggingFaceEmbedding\nfrom llama_index.vector_stores.chroma import ChromaVectorStore\n\n# --- Configuration ---\n# For a fully local setup, use a local LLM and Embedding model.\n# If using OpenAI, uncomment and set API key:\n# from llama_index.llms.openai import OpenAI\n# os.environ[\"OPENAI_API_KEY\"] = os.environ.get(\"OPENAI_API_KEY\", \"\")\n# Settings.llm = OpenAI()\n\n# Using a local embedding model for demonstration without external API keys\nSettings.embed_model = HuggingFaceEmbedding(model_name=\"BAAI/bge-small-en-v1.5\")\n\n# 1. Create a Chroma client and collection\n# Use EphemeralClient for in-memory, or PersistentClient for disk storage\nchroma_client = chromadb.EphemeralClient() # For persistent storage: chromadb.PersistentClient(path=\"./chroma_db\")\nchroma_collection = chroma_client.create_collection(\"my_documents_collection\")\n\n# 2. Set up the ChromaVectorStore\nvector_store = ChromaVectorStore(chroma_collection=chroma_collection)\n\n# 3. Create a StorageContext and link the vector store\nstorage_context = StorageContext.from_defaults(vector_store=vector_store)\n\n# 4. Load documents (e.g., from a 'data' directory)\n# Create a dummy file for demonstration if 'data' doesn't exist\nif not os.path.exists(\"data\"): os.makedirs(\"data\")\nwith open(\"data/example.txt\", \"w\") as f:\n    f.write(\"The quick brown fox jumps over the lazy dog. LlamaIndex is great.\")\n\ndocuments = SimpleDirectoryReader(\"data\").load_data()\n\n# 5. Create a VectorStoreIndex from documents\n# embed_model is implicitly used from Settings.embed_model\nindex = VectorStoreIndex.from_documents(documents, storage_context=storage_context)\n\n# 6. Query the index\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"What is LlamaIndex?\")\n\nprint(response.response)","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `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.","message":"With 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.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Always install `chromadb` alongside `llama-index-vector-stores-chroma`: `pip install llama-index-vector-stores-chroma chromadb`.","message":"The `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.","severity":"gotcha","affected_versions":"All"},{"fix":"Try 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`.","message":"Version conflicts, particularly involving `onnxruntime`, can occur between `llama-index-vector-stores-chroma` and other installed packages (especially `chromadb`). This often manifests during installation.","severity":"gotcha","affected_versions":"All"},{"fix":"Migrate to `VectorStoreIndex`, `Settings`, and direct LLM/embedding model configuration. Refer to the LlamaIndex v0.10 migration guide.","message":"Older LlamaIndex concepts like `GPTSimpleVectorIndex`, `GPTVectorStoreIndex`, `ServiceContext`, and `LLMPredictor` have been deprecated or renamed.","severity":"deprecated","affected_versions":">=0.10.0"},{"fix":"Ensure `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.","message":"Calling 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`.","severity":"gotcha","affected_versions":"ChromaDB >= 0.4.0 (affecting llama-index-vector-stores-chroma versions that rely on it)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install llama-index-vector-stores-chroma chromadb`. Ensure your import statement is `from llama_index.vector_stores.chroma import ChromaVectorStore`.","cause":"The `llama-index-vector-stores-chroma` package is not installed, or `chromadb` (a peer dependency) is missing. Post LlamaIndex v0.10, integration packages are separate.","error":"ModuleNotFoundError: No module named 'llama_index.vector_stores'"},{"fix":"Try `pip install --upgrade pip` then `pip install --no-cache-dir llama-index-vector-stores-chroma chromadb`. If the issue persists, consider installing `onnxruntime` via `conda-forge` first if using Anaconda/Miniconda (`conda install -c conda-forge onnxruntime`) then `pip install`.","cause":"Dependency conflict with `onnxruntime`, often arising when `chromadb` is installed with other packages that have different `onnxruntime` requirements.","error":"ERROR: Cannot install llama-index-cli because these package versions have conflicting dependencies. The conflict is caused by: llama-index-vector-stores-chroma X.Y.Z depends on onnxruntime<2.0.0 and >=1.17.0"},{"fix":"Change your import from `from llama_index import VectorStoreIndex` to `from llama_index.core import VectorStoreIndex`.","cause":"Breaking change in LlamaIndex v0.10+ where core components were moved to `llama_index.core`.","error":"ImportError: cannot import name 'VectorStoreIndex' from 'llama_index' (unknown location)"},{"fix":"Modify your code to ensure that the `node_ids` parameter passed to `ChromaVectorStore.get_nodes` (or any underlying ChromaDB call) is always a list with at least one ID, or use appropriate filtering methods if you intend to retrieve nodes without specifying IDs.","cause":"This error occurs within ChromaDB's validation when `get_nodes` is called with an empty list for `node_ids`, which is then passed down to ChromaDB's internal `_get` method.","error":"Expected IDs to be a non-empty list, got 0 IDs"}]}