Chroma Getting Started: Quickstart Guide (2026)

Getting started overview

Chroma is an open-source embedding database designed for AI applications. It supports both a self-hosted option for local development and a managed cloud service. This guide outlines the steps to get started with Chroma, covering account creation for Chroma Cloud, obtaining necessary credentials, and making an initial request. For self-hosted instances, credential steps are not required, as access is local to the environment where Chroma is installed.

The primary client libraries available for interacting with Chroma are Python and JavaScript, which facilitate integration into machine learning workflows and web applications, respectively. The quickstart process typically involves installing the chosen client library, initializing a Chroma client, and then interacting with collections to store and retrieve embeddings.

Here is an overview of the initial steps required to get Chroma operational:

Create an account and get keys

To use Chroma Cloud, you need to create an account and obtain an API key. For self-hosted Chroma instances, this step is not necessary as access is managed locally without central authentication.

Chroma Cloud Signup

1. Navigate to the Chroma website.
2. Locate the option to sign up for Chroma Cloud. This usually involves providing an email address and creating a password.
3. Follow any verification steps, such as confirming your email address.
4. Once signed in, you will typically be directed to a dashboard.

API Key Retrieval

After signing into your Chroma Cloud account, your API key will be available in your account settings or dashboard. This key authenticates your requests to the Chroma Cloud service.

1. From your Chroma Cloud dashboard, look for sections like "API Keys," "Settings," or "Developer."
2. Generate a new API key if one is not already provided. Ensure you copy this key immediately, as it may only be shown once.
3. Store your API key securely. It is recommended to use environment variables for managing API keys in your application, rather than embedding them directly in your code. For example, you might set an environment variable like CHROMA_API_KEY.

Self-Hosted Setup

For a self-hosted Chroma instance, the process involves installing the Chroma client locally. No account creation or API keys are required for local operation.

1. Install the Chroma Python client using pip: pip install chromadb.
2. For persistent storage in a local environment, you can specify a path when initializing the client.

Your first request

This section demonstrates how to make a first request using either the Python or JavaScript client. The example will cover initializing the client, creating a collection, and adding data.

Python Example

First, ensure you have the ChromaDB Python client installed (Chroma installation guide).

import chromadb

# For Chroma Cloud
# client = chromadb.HttpClient(host="YOUR_CHROMA_CLOUD_HOST", port="8000", headers={"X-Chroma-API-Key": "YOUR_API_KEY"})

# For a local, in-memory Chroma instance (non-persistent)
client = chromadb.Client()

# For a local, persistent Chroma instance
# client = chromadb.PersistentClient(path="./chroma_data")

# Create a collection
collection_name = "my_first_collection"
try:
    collection = client.get_or_create_collection(name=collection_name)
    print(f"Collection '{collection_name}' ready.")
except Exception as e:
    print(f"Error getting or creating collection: {e}")
    exit()

# Add documents and their embeddings
documents = [
    "This is document one",
    "This is document two",
    "This is document three"
]

# Example embeddings (replace with actual embeddings from an embedding model)
# These are placeholder vectors. In a real application, you'd use a model
# like OpenAI's `text-embedding-ada-002` or a Sentence Transformer.
embeddings = [
    [1.1, 2.3, 3.2, 4.5, 5.1],
    [6.2, 7.1, 8.3, 9.4, 1.5],
    [2.3, 3.4, 4.5, 5.6, 6.7]
]

metadatas = [
    {"source": "web"},
    {"source": "api"},
    {"source": "local"}
]

ids = ["doc1", "doc2", "doc3"]

try:
    collection.add(
        documents=documents,
        embeddings=embeddings,
        metadatas=metadatas,
        ids=ids
    )
    print(f"Added {len(documents)} documents to '{collection_name}'.")
except Exception as e:
    print(f"Error adding documents: {e}")
    exit()

# Query the collection
query_texts = ["document one"]

try:
    results = collection.query(
        query_texts=query_texts,
        n_results=1,
        include=['documents', 'distances', 'metadatas', 'embeddings']
    )
    print("\nQuery Results:")
    for i, doc in enumerate(results['documents'][0]):
        print(f"  Document: {doc}")
        print(f"  Distance: {results['distances'][0][i]}")
        print(f"  Metadata: {results['metadatas'][0][i]}")
except Exception as e:
    print(f"Error querying documents: {e}")

JavaScript Example

First, install the ChromaDB JavaScript client (Chroma installation instructions):

npm install chromadb
# or
yarn add chromadb

Then, use the following code:

import { ChromaClient, LocalClient } from "chromadb";

async function runChromaExample() {
    // For Chroma Cloud
    // const client = new ChromaClient({
    //   path: "YOUR_CHROMA_CLOUD_HOST:8000",
    //   headers: { "X-Chroma-API-Key": "YOUR_API_KEY" },
    // });

    // For a local, in-memory Chroma instance (non-persistent)
    const client = new LocalClient();

    // For a local, persistent Chroma instance (requires a server to be running, e.g., via `chroma run --path ./chroma_data`)
    // const client = new ChromaClient({
    //   path: "http://localhost:8000",
    // });

    const collectionName = "my_first_js_collection";
    let collection;

    try {
        collection = await client.getOrCreateCollection({
            name: collectionName,
        });
        console.log(`Collection '${collectionName}' ready.`);
    } catch (e) {
        console.error(`Error getting or creating collection: ${e.message}`);
        return;
    }

    const documents = [
        "This is document one from JS",
        "This is document two from JS",
        "This is document three from JS",
    ];

    // Example embeddings (replace with actual embeddings from an embedding model)
    const embeddings = [
        [0.1, 0.2, 0.3, 0.4, 0.5],
        [0.6, 0.7, 0.8, 0.9, 0.1],
        [0.2, 0.3, 0.4, 0.5, 0.6],
    ];

    const metadatas = [
        { source: "js-web" },
        { source: "js-api" },
        { source: "js-local" },
    ];

    const ids = ["js_doc1", "js_doc2", "js_doc3"];

    try {
        await collection.add({
            documents: documents,
            embeddings: embeddings,
            metadatas: metadatas,
            ids: ids,
        });
        console.log(`Added ${documents.length} documents to '${collectionName}'.`);
    } catch (e) {
        console.error(`Error adding documents: ${e.message}`);
        return;
    }

    const queryTexts = ["document one from JS"];

    try {
        const results = await collection.query({
            queryTexts: queryTexts,
            nResults: 1,
            include: ['documents', 'distances', 'metadatas', 'embeddings'],
        });
        console.log("\nQuery Results:");
        if (results.documents && results.documents[0]) {
            results.documents[0].forEach((doc, i) => {
                console.log(`  Document: ${doc}`);
                console.log(`  Distance: ${results.distances[0][i]}`);
                console.log(`  Metadata:`, results.metadatas[0][i]);
            });
        }
    } catch (e) {
        console.error(`Error querying documents: ${e.message}`);
    }
}

runChromaExample();

Common next steps

After successfully performing your first interaction with Chroma, consider these next steps to further develop your application:

• Integrate an Embedding Model: The examples above use placeholder embeddings. In a real-world scenario, you would integrate a robust embedding model to convert text, images, or other data into dense vector representations. Common choices include models from Google's Vertex AI, OpenAI, or various open-source models available through libraries like Hugging Face Transformers.
• Explore Advanced Querying: Chroma supports various query types beyond simple similarity search. Investigate filtering by metadata, querying with multiple embeddings, and specifying different distance functions to refine your search results (Chroma usage patterns).
• Implement Retrieval-Augmented Generation (RAG): For LLM applications, integrate Chroma into a RAG pipeline. This involves using Chroma to retrieve relevant context based on a user query, which is then fed to an LLM to generate a more informed response.
• Monitor and Scale: If using Chroma Cloud, monitor your usage and performance metrics. For self-hosted deployments, consider deploying Chroma in a production-ready environment using Docker or Kubernetes for scalability and management (Chroma deployment options).
• Data Management and Backup: Establish strategies for managing your data within Chroma, including updating and deleting documents. For persistent instances, implement backup procedures for your Chroma data directories.
• Security Best Practices: For Chroma Cloud, rotate API keys periodically. For self-hosted instances, secure network access to your Chroma server.
• Explore Integrations: Chroma integrates with frameworks like LangChain and LlamaIndex to simplify building LLM applications. Explore these integrations to streamline your development process.

Troubleshooting the first call

When making your first API call to Chroma, you might encounter issues. Here are some common problems and their solutions:

• API Key or Host Misconfiguration (Chroma Cloud):
  • Issue: Invalid API key, incorrect host URL, or missing headers.
  • Solution: Double-check that your X-Chroma-API-Key header contains the correct API key obtained from your Chroma Cloud dashboard. Verify that the host URL matches the endpoint provided by Chroma Cloud. Ensure all required headers are present as specified in the Chroma API reference.
• Client Initialization Errors:
  • Issue: The client is not initialized correctly, especially when switching between in-memory, persistent local, or cloud modes.
  • Solution: Review the client initialization code. For in-memory, use chromadb.Client(). For persistent local, use chromadb.PersistentClient(path="./your_data_path"). For Chroma Cloud, use chromadb.HttpClient(...) with the correct host, port, and authentication headers.
• Collection Creation Failures:
  • Issue: Unable to create or retrieve a collection.
  • Solution: Check for network connectivity if using Chroma Cloud. Ensure the collection name adheres to Chroma's naming conventions (e.g., no special characters, appropriate length). If running a persistent local instance, verify that the specified path is writable and accessible.
• Embedding Dimension Mismatch:
  • Issue: Attempting to add embeddings with inconsistent dimensions to a collection.
  • Solution: Chroma collections enforce a consistent embedding dimension. Ensure all embeddings added to a collection have the same vector length. If you need to change the dimension, you typically need to create a new collection (Chroma embeddings documentation).
• Missing or Incorrect Dependencies:
  • Issue: The client library is not installed, or there are version conflicts.
  • Solution: Re-run pip install chromadb (Python) or npm install chromadb (JavaScript). Consider creating a virtual environment (Python) or clearing node_modules and reinstalling (JavaScript) to resolve dependency issues.
• Server Not Running (Self-Hosted Persistent Mode):
  • Issue: When using the persistent client in self-hosted mode without running the Chroma server.
  • Solution: Ensure you have started the Chroma server process, often with a command like chroma run --path ./chroma_data, before attempting to connect with chromadb.HttpClient pointing to a local address like http://localhost:8000.