Why ChromaDB?

ChromaDB is an open-source, lightweight vector database that runs locally. It's perfect for development, prototyping, and applications that need offline vector search without cloud dependencies.

Installation

pip install chromadb

Creating a Client

import chromadb

# In-memory (ephemeral)
client = chromadb.Client()

# Persistent storage
client = chromadb.PersistentClient(path="./chroma_data")

# Client-server mode
client = chromadb.HttpClient(host="localhost", port=8000)

Working with Collections

Collections are the primary organizational unit:

# Create or get a collection
collection = client.get_or_create_collection(
    name="articles",
    metadata={"hnsw:space": "cosine"}  # Distance metric
)

# Add documents (auto-embeds with default model)
collection.add(
    documents=["The sky is blue", "Grass is green", "The sun is yellow"],
    ids=["doc1", "doc2", "doc3"],
    metadatas=[{"topic": "sky"}, {"topic": "nature"}, {"topic": "sky"}],
)

Collection Management

• List: client.list_collections()
• Get: client.get_collection("name")
• Delete: client.delete_collection("name")
• Count: collection.count() — number of items

Common Pitfalls

A frequent mistake is mixing different embedding models across sessions. If you create a collection with the default Sentence Transformer model but later query it using OpenAI embeddings, results will be meaningless — vectors from different embedding spaces are not comparable. Always persist the embedding function setting alongside the collection name, for example in a config file or environment variable.

Another pitfall is forgetting to set a persistent path in development. Starting with chromadb.Client() (in-memory) is fine for quick experiments, but all data disappears when the process exits. Switch to PersistentClient as soon as you want to retain data between runs.

Best Practice: Collection Naming Convention

Use a descriptive, versioned naming scheme to avoid conflicts when you change embedding models:

# Include the embedding model name in the collection name
collection = client.get_or_create_collection("docs_minilm_v1")

# When you upgrade to a new embedding model, create a new collection
collection_v2 = client.get_or_create_collection("docs_openai_small_v2")

This pattern makes it easy to run A/B comparisons between embedding models without risk of collision.

Named Product Reference: ChromaDB vs. Weaviate

For teams evaluating local alternatives, ChromaDB and Weaviate are often compared. ChromaDB's biggest advantage is zero-infrastructure setup — no Docker container is required for local development. Weaviate, by contrast, requires running a Docker service even locally but offers more advanced features like cross-references between objects and built-in BM25 hybrid search. For projects under 1 million vectors that need fast iteration, ChromaDB wins on developer experience.