Install ChromaDB in Python

ChromaDB is an open-source vector database. It helps you store and search embeddings. It is fast, easy to use, and works offline. In this guide, you will learn how to install ChromaDB in Python.

We will cover setup, verification, and a basic example. This tutorial is for beginners. You only need Python installed on your machine.

What is ChromaDB?

ChromaDB is designed for AI applications. It stores vector embeddings from models like OpenAI or Hugging Face. You can use it for semantic search, recommendation systems, or RAG pipelines.

It supports Python, JavaScript, and CLI. The Python client is the most popular. It works with pip and requires no external server. This makes it perfect for local development.

Prerequisites

Before you install ChromaDB, check your Python version. You need Python 3.8 or higher. Open your terminal or command prompt.

Run this command to check your Python version:

python --version

If you see Python 3.8 or newer, you are ready. If not, download the latest Python from python.org. Make sure to add Python to your PATH during installation.

Install ChromaDB with pip

The easiest way to install ChromaDB is using pip. Pip is the package installer for Python. It comes with Python by default.

Open your terminal and run this command:

pip install chromadb

This will download and install ChromaDB and its dependencies. The process usually takes a few seconds. You will see output like this:

Collecting chromadb
  Downloading chromadb-0.5.0-py3-none-any.whl (1.2 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.2/1.2 MB 3.5 MB/s eta 0:00:00
Installing collected packages: chromadb, hnswlib, etc.
Successfully installed chromadb-0.5.0 hnswlib-0.8.0

If you get a permission error, use pip install --user chromadb or run the terminal as administrator. For virtual environments, activate the environment first.

Verify the Installation

After installation, verify that ChromaDB works. Open a Python shell or create a new Python file. Import the library and check the version.

import chromadb
print(chromadb.__version__)

Run the script. You should see the version number printed:

0.5.0

No errors means the installation succeeded. If you see an ImportError, try reinstalling with pip install --upgrade chromadb.

Your First ChromaDB Collection

Now let's create a simple collection. A collection is like a table in a database. It stores your documents and their embeddings.

Here is a complete example:

import chromadb

# Create a client
client = chromadb.Client()

# Create a collection
collection = client.create_collection("my_first_collection")

# Add documents
collection.add(
    documents=["Hello world", "ChromaDB is awesome"],
    ids=["doc1", "doc2"]
)

# Query the collection
results = collection.query(query_texts=["world"], n_results=1)
print(results)

When you run this code, you get output like:

{'ids': [['doc1']], 'distances': [[1.0]], 'metadatas': [[None]], 'documents': [['Hello world']]}

The query found the document containing "world". This shows that ChromaDB is working correctly. You can now build more complex applications.

Common Installation Issues

Sometimes installation fails. Here are common problems and fixes.

Problem: pip not found
Run python -m pip install chromadb instead. This uses the Python module directly.

Problem: Dependency conflicts
Create a fresh virtual environment. Use python -m venv venv and activate it. Then install ChromaDB.

Problem: Slow download
Use a mirror. For example: pip install chromadb -i https://pypi.org/simple

Problem: HNSWlib compilation error
Install the precompiled wheel. On Windows, use pip install chromadb --only-binary=:all:

Using ChromaDB with Persistent Storage

By default, ChromaDB stores data in memory. To save data to disk, use the PersistentClient.

import chromadb

# Create a persistent client
client = chromadb.PersistentClient(path="./chroma_data")

# Create or get a collection
collection = client.get_or_create_collection("persistent_collection")

# Add documents
collection.add(
    documents=["Data persists across sessions"],
    ids=["doc3"]
)

# Query
results = collection.query(query_texts=["data"], n_results=1)
print(results)

Now your data stays on disk. You can restart your program and still access the data. This is useful for production applications.

Integrating with Other Libraries

ChromaDB works well with other Python libraries. You can combine it with LangChain or OpenAI for powerful AI pipelines.

For example, to use ChromaDB as a vector store in LangChain:

from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings

# Create embeddings
embeddings = OpenAIEmbeddings()

# Create vector store
vectorstore = Chroma(
    collection_name="langchain_store",
    embedding_function=embeddings,
    persist_directory="./chroma_langchain"
)

# Add texts
vectorstore.add_texts(["LangChain integration works"])

# Search
results = vectorstore.similarity_search("integration")
print(results)

This example shows how ChromaDB fits into modern AI workflows. It is flexible and easy to integrate.

Best Practices for ChromaDB

Follow these tips to get the most out of ChromaDB.

Use batch operations when adding many documents. This is faster than adding one by one. Use the add method with lists.

Set a collection name that describes your data. This helps with organization. Use names like "product_embeddings" or "user_profiles".

Handle metadata carefully. ChromaDB stores metadata alongside documents. Use it to filter results later.

Monitor memory usage. Large collections can use significant RAM. Use persistent storage or limit collection size.

Conclusion

Installing ChromaDB in Python is simple. You just run pip install chromadb. After that, you can create collections, add documents, and query them. The library is beginner-friendly and works offline.

We covered verification, common issues, persistent storage, and integration. Now you can start building vector search applications. ChromaDB is a powerful tool for your AI projects.

Try the examples in this guide. Experiment with different queries. You will quickly see how ChromaDB makes vector search easy.