🎨

ChromaDB

Vector Databases

Open-source embedding database built for AI applications. Simple, scalable, and Python-first

Deploy Now Browse All Apps

Deployment Info

Deployment: 2-5 min
category: Vector Databases
Min RAM: 1024MB
Support: Tickets and email

Share this guide

Overview

ChromaDB is an open-source vector database specifically designed for building AI-native applications with large language models (LLMs) and embeddings. As the AI-native embedding database, ChromaDB makes it simple to build LLM applications by providing a lightning-fast, developer-friendly solution for storing and querying vector embeddings alongside metadata.

At the heart of ChromaDB is its focus on simplicity and developer experience. Unlike traditional databases that require complex setup and configuration, ChromaDB can be up and running with just a few lines of Python code. It's designed to feel pythonic and intuitive, with a clean API that abstracts away the complexity of vector similarity search while still providing powerful functionality when you need it.

ChromaDB excels at semantic search and retrieval-augmented generation (RAG), the two most common patterns in LLM applications. When you ask a question to an LLM with RAG, ChromaDB finds the most relevant context from your knowledge base by performing similarity searches on vector embeddings. This enables AI applications to access and reason over your proprietary data, documentation, or knowledge bases without fine-tuning the entire model.

The database stores embeddings (high-dimensional vectors that represent text, images, or other data) along with their associated metadata and documents. ChromaDB handles the embedding generation process seamlessly through integrations with popular embedding models like OpenAI, Cohere, and Sentence Transformers. You simply provide your documents, and ChromaDB takes care of generating and storing the embeddings.

ChromaDB offers multiple deployment modes to fit your needs. Run it in-memory for development and testing, persist to disk for single-machine deployments, or scale horizontally with the distributed client-server architecture for production workloads. The server mode supports authentication, multi-tenancy, and can handle billions of embeddings across thousands of collections.

With built-in support for filtering, metadata queries, and hybrid search capabilities, ChromaDB enables sophisticated retrieval strategies beyond simple vector similarity. You can combine semantic search with keyword filtering, date ranges, or custom metadata to precisely target the information your LLM needs. The platform also includes observability features to help you understand and optimize your vector search performance.

Key Features

Simple Python API

Intuitive, pythonic interface with minimal setup - start querying embeddings in just 3 lines of code

Built-in Embedding Support

Automatic embedding generation with OpenAI, Cohere, Sentence Transformers, and custom embedding functions

Semantic Search & RAG

Lightning-fast similarity search optimized for retrieval-augmented generation and LLM applications

Flexible Deployment

Run in-memory, persist to disk, or deploy as distributed client-server with horizontal scaling

Rich Metadata Filtering

Combine vector similarity with metadata filters, date ranges, and boolean logic for precise retrieval

Production-Ready Features

Multi-tenancy, authentication, observability, backup/restore, and billion-scale embedding support

Use Cases

• Retrieval-Augmented Generation (RAG): Provide LLMs with relevant context from your knowledge base for accurate, domain-specific responses
• Semantic Search Applications: Build intelligent search engines that understand meaning and intent beyond keyword matching
• Question Answering Systems: Create chatbots and virtual assistants that can answer questions using your proprietary documentation
• Document Analysis: Enable AI to search and analyze large document collections (legal, medical, research papers)
• Recommendation Systems: Power content recommendations based on semantic similarity rather than collaborative filtering
• Code Search: Help developers find relevant code snippets and documentation across large codebases
• Multi-Modal Search: Search across text, images, and other data types using embedding-based similarity

Installation Guide

Installation on Ubuntu VPS:

1. Install Python and Dependencies:
sudo apt update && sudo apt upgrade -y
sudo apt install python3.10 python3-pip python3-venv -y
2. Create Virtual Environment:
mkdir chromadb-server
cd chromadb-server
python3 -m venv venv
source venv/bin/activate
3. Install ChromaDB:
pip install chromadb
4. Quick Test (In-Memory Mode):
import chromadb

# Create client
client = chromadb.Client()

# Create collection
collection = client.create_collection(name="test_collection")

# Add documents
collection.add(
    documents=["This is a document", "This is another document"],
    metadatas=[{"source": "doc1"}, {"source": "doc2"}],
    ids=["id1", "id2"]
)

# Query
results = collection.query(
    query_texts=["This is a query document"],
    n_results=2
)

print(results)
5. Install ChromaDB Server (Production):
pip install chromadb[server]
6. Run ChromaDB Server:
# Start server on localhost:8000
chroma run --path ./chroma_data --host 0.0.0.0 --port 8000

# Or with authentication
export CHROMA_SERVER_AUTH_CREDENTIALS="admin:secure_password"
export CHROMA_SERVER_AUTH_PROVIDER="chromadb.auth.basic.BasicAuthServerProvider"
chroma run --path ./chroma_data --host 0.0.0.0 --port 8000
7. Docker Installation (Recommended for Production):
# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  chromadb:
    image: chromadb/chroma:latest
    container_name: chromadb
    ports:
      - "8000:8000"
    volumes:
      - ./chroma_data:/chroma/chroma
    environment:
      - CHROMA_SERVER_AUTH_CREDENTIALS=admin:secure_password
      - CHROMA_SERVER_AUTH_PROVIDER=chromadb.auth.basic.BasicAuthServerProvider
      - IS_PERSISTENT=TRUE
      - ANONYMIZED_TELEMETRY=FALSE
    restart: unless-stopped
EOF

# Start service
docker-compose up -d

# Check logs
docker-compose logs -f chromadb
8. Configure systemd Service (Non-Docker):
sudo nano /etc/systemd/system/chromadb.service
Add:
[Unit]
Description=ChromaDB Server
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/chromadb-server
Environment="PATH=/home/ubuntu/chromadb-server/venv/bin"
Environment="CHROMA_SERVER_AUTH_CREDENTIALS=admin:secure_password"
Environment="CHROMA_SERVER_AUTH_PROVIDER=chromadb.auth.basic.BasicAuthServerProvider"
ExecStart=/home/ubuntu/chromadb-server/venv/bin/chroma run --path /home/ubuntu/chromadb-server/chroma_data --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
Enable and start:
sudo systemctl daemon-reload
sudo systemctl enable chromadb
sudo systemctl start chromadb
sudo systemctl status chromadb
9. Configure Nginx Reverse Proxy:
sudo nano /etc/nginx/sites-available/chromadb
Add:
server {
    listen 80;
    server_name chroma.yourdomain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
Enable and get SSL:
sudo ln -s /etc/nginx/sites-available/chromadb /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo certbot --nginx -d chroma.yourdomain.com
10. Test Connection:
import chromadb

# Connect to server
client = chromadb.HttpClient(
    host='chroma.yourdomain.com',
    port=443,
    ssl=True,
    headers={"Authorization": "Basic YWRtaW46c2VjdXJlX3Bhc3N3b3Jk"}  # base64 of admin:secure_password
)

# List collections
print(client.list_collections())

Configuration Tips

Essential Configuration:

1. Client Configuration:
import chromadb
from chromadb.config import Settings

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

# Persistent (single machine)
client = chromadb.PersistentClient(path="/path/to/chroma/data")

# HTTP Client (production)
client = chromadb.HttpClient(
    host='localhost',
    port=8000,
    settings=Settings(
        chroma_client_auth_provider="chromadb.auth.basic.BasicAuthClientProvider",
        chroma_client_auth_credentials="admin:password"
    )
)
2. Collection Management:
# Create collection with custom embedding function
collection = client.create_collection(
    name="my_collection",
    embedding_function=chromadb.utils.embedding_functions.OpenAIEmbeddingFunction(
        api_key="your-openai-key",
        model_name="text-embedding-3-small"
    ),
    metadata={"description": "My vector collection"}
)

# Get or create collection
collection = client.get_or_create_collection(name="my_collection")

# Delete collection
client.delete_collection(name="my_collection")
3. Adding Documents:
collection.add(
    documents=["Document 1 text", "Document 2 text", "Document 3 text"],
    metadatas=[
        {"source": "web", "date": "2024-01-01"},
        {"source": "pdf", "date": "2024-01-02"},
        {"source": "api", "date": "2024-01-03"}
    ],
    ids=["id1", "id2", "id3"]
)

# Add with custom embeddings
collection.add(
    embeddings=[[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
    documents=["doc1", "doc2"],
    ids=["id1", "id2"]
)
4. Querying with Filters:
# Semantic search
results = collection.query(
    query_texts=["What is RAG?"],
    n_results=10
)

# With metadata filtering
results = collection.query(
    query_texts=["What is RAG?"],
    n_results=10,
    where={"source": "web"},  # Exact match
    where_document={"$contains": "retrieval"}  # Full-text search
)

# Complex filters
results = collection.query(
    query_texts=["machine learning"],
    n_results=5,
    where={
        "$and": [
            {"source": {"$in": ["web", "pdf"]}},
            {"date": {"$gte": "2024-01-01"}}
        ]
    }
)
5. Embedding Functions:
# OpenAI embeddings
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction
embedding_fn = OpenAIEmbeddingFunction(
    api_key="your-key",
    model_name="text-embedding-3-small"
)

# Sentence Transformers (local)
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction
embedding_fn = SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

# Cohere embeddings
from chromadb.utils.embedding_functions import CohereEmbeddingFunction
embedding_fn = CohereEmbeddingFunction(
    api_key="your-cohere-key",
    model_name="embed-english-v3.0"
)

# Custom embedding function
from chromadb import EmbeddingFunction
class MyEmbeddingFunction(EmbeddingFunction):
    def __call__(self, texts):
        # Your embedding logic here
        return embeddings
6. Update and Delete:
# Update documents
collection.update(
    ids=["id1"],
    documents=["Updated document text"],
    metadatas=[{"source": "updated"}]
)

# Delete by IDs
collection.delete(ids=["id1", "id2"])

# Delete by filter
collection.delete(where={"source": "old"})
7. Environment Variables (Server):
# Authentication
export CHROMA_SERVER_AUTH_CREDENTIALS="admin:password"
export CHROMA_SERVER_AUTH_PROVIDER="chromadb.auth.basic.BasicAuthServerProvider"

# Persistence
export IS_PERSISTENT=TRUE
export PERSIST_DIRECTORY=/path/to/data

# Performance
export CHROMA_SERVER_HTTP_PORT=8000
export CHROMA_OTEL_COLLECTION_ENDPOINT=""  # Disable telemetry
export ANONYMIZED_TELEMETRY=FALSE
8. Performance Optimization:
# Batch operations
collection.add(
    documents=large_document_list,
    ids=large_id_list,
    metadatas=large_metadata_list
)

# Use persistent client for disk caching
client = chromadb.PersistentClient(path="./chroma_data")

# Optimize n_results for speed
results = collection.query(query_texts=["query"], n_results=10)  # Lower is faster
Best Practices:
- Use persistent or server mode for production (not in-memory)
- Batch document additions for better performance
- Choose appropriate embedding models (size vs accuracy trade-off)
- Index metadata fields you frequently filter on
- Use meaningful collection names and metadata
- Implement proper authentication in server mode
- Regular backups of chroma_data directory
- Monitor embedding generation costs (API-based models)
- Use local embedding models (Sentence Transformers) for cost savings
- Implement retry logic for API-based embedding functions

Technical Requirements

System Requirements

  • Memory: 1024MB RAM

Rate This Article

★★★★★
-
Loading...

Related Applications

🎯
Qdrant
Vector Databases

High-performance vector database with extended filtering support. Perfect for neural network embeddings
🦅
Milvus
Vector Databases

Cloud-native vector database for scalable similarity search and AI applications
🕸️
Weaviate
Vector Databases

Open-source vector search engine with built-in vectorization and hybrid search capabilities
🌲
Pinecone (OSS Alternative)
Vector Databases

pgvector - PostgreSQL extension for vector similarity search, the open-source Pinecone alternative

Ready to Deploy Your Application? ChromaDB?

Get started in minutes with our simple VPS deployment process

Create VPS Server View Pricing

Deploy in about 2 minutes • Full root access • Support by ticket and email