chroma Documentation

1. Project Overview & Quickstart (chroma-core/chroma) Copy Chapter

File: README.md Copy Chapter

pip install chromadb # python client
# for javascript, npm install chromadb!
# for client-server mode, chroma run --path /chroma_db_path

Chroma Cloud Copy Chapter

Our hosted service, Chroma Cloud, powers serverless vector, hybrid, and full-text search. It's extremely fast, cost-effective, scalable and painless. Create a DB and try it out in under 30 seconds with $5 of free credits.

Get started with Chroma Cloud

API Copy Chapter

The core API is only 4 functions (run our 💡 Google Colab):

import chromadb
# setup Chroma in-memory, for easy prototyping. Can add persistence easily!
client = chromadb.Client()

# Create collection. get_collection, get_or_create_collection, delete_collection also available!
collection = client.create_collection("all-my-documents")

# Add docs to the collection. Can also update and delete. Row-based API coming soon!
collection.add(
    documents=["This is document1", "This is document2"], # we handle tokenization, embedding, and indexing automatically. You can skip that and add your own embeddings as well
    metadatas=[{"source": "notion"}, {"source": "google-docs"}], # filter on these!
    ids=["doc1", "doc2"], # unique for each doc
)

# Query/search 2 most similar results. You can also .get by id
results = collection.query(
    query_texts=["This is a query document"],
    n_results=2,
    # where={"metadata_field": "is_equal_to_this"}, # optional filter
    # where_document={"$contains":"search_string"}  # optional filter
)

Learn about all features on our Docs

Get involved Copy Chapter

Chroma is a rapidly developing project. We welcome PR contributors and ideas for how to improve the project.

• Join the conversation on Discord - #contributing channel
• Review the 🛣️ Roadmap and contribute your ideas
• Grab an issue and open a PR - Good first issue tag
• Read our contributing guide

Release Cadence
We currently release new tagged versions of the pypi and npm packages on Mondays. Hotfixes go out at any time during the week.

License Copy Chapter

Apache 2.0

File: chromadb/telemetry/README.md Copy Chapter

Telemetry

This directory holds all the telemetry for Chroma.

• product/ contains anonymized product telemetry which we, Chroma, collect so we can
  understand usage patterns. For more information, see https://docs.trychroma.com/telemetry.
• opentelemetry/ contains all of the config for Chroma's OpenTelemetry
  setup. These metrics are not sent back to Chroma -- anyone operating a Chroma instance
  can use the OpenTelemetry metrics and traces to understand how their instance of Chroma
  is behaving.

File: chromadb/utils/embedding_functions/schemas/README.md Copy Chapter

Embedding Function Schemas

This directory contains JSON schemas for all embedding functions in Chroma. The purpose of having this schema is to support cross language compatibility, and to validate that changes in one client library do not accidentally diverge from others.

Schema Structure Copy Chapter

Each schema follows the JSON Schema Draft-07 specification and includes:

• version: The version of the schema
• title: The title of the schema
• description: A description of the schema
• properties: The properties that can be configured for the embedding function
• required: The properties that are required for the embedding function
• additionalProperties: Whether additional properties are allowed (always set to false to ensure strict validation)

Usage Copy Chapter

The schemas can be used to validate the configuration of embedding functions using the validate_config function:

from chromadb.utils.embedding_functions.schemas import validate_config

# Validate a configuration
config = {
    "api_key_env_var": "CHROMA_OPENAI_API_KEY",
    "model_name": "text-embedding-ada-002"
}
validate_config(config, "openai")

Adding New Schemas Copy Chapter

To add a new schema:

1. Create a new JSON file in this directory with the name of the embedding function (e.g., new_function.json)
2. Define the schema following the JSON Schema Draft-07 specification
3. Update the embedding function to use the schema for validation

Schema Versioning Copy Chapter

Each schema includes a version number to support future changes to embedding function configurations. When making changes to a schema, increment the version number to ensure backward compatibility.

File: clients/python/README.md Copy Chapter

pip install chromadb-client # python http-client only library

To connect to your server and perform operations using the client only library, you can do the following:

import chromadb
# Example setup of the client to connect to your chroma server
client = chromadb.HttpClient(host="localhost", port=8000)

collection = client.create_collection("all-my-documents")

collection.add(
    documents=["This is document1", "This is document2"],
    metadatas=[{"source": "notion"}, {"source": "google-docs"}], # filter on these!
    ids=["doc1", "doc2"], # unique for each doc
    embeddings = [[1.2, 2.1, ...], [1.2, 2.1, ...]]
)

results = collection.query(
    query_texts=["This is a query document"],
    n_results=2,
    # where={"metadata_field": "is_equal_to_this"}, # optional filter
    # where_document={"$contains":"search_string"}  # optional filter
)

License Copy Chapter

Apache 2.0

File: clients/js/examples/node/README.md Copy Chapter

Node Example

This is an example of how to use ChromaDB with Node.js.

Getting Started Copy Chapter

1. Make sure you have Chroma running locally at http://localhost:8000
2. Run pnpm install to install dependencies
3. Run one of the following commands:

• pnpm dev - Run the example with the default bundled package
• pnpm dev:bundled - Run the example with the bundled chromadb package
• pnpm dev:client - Run the example with the chromadb-client package (peer dependencies)

Package Options Copy Chapter

This example demonstrates both ChromaDB package options:

1. chromadb (Bundled Package): Includes all embedding libraries as dependencies.

   • Good for simple projects or when you want everything included.
   • Import with: const chroma = require("chromadb");

2. chromadb-client (Client Package): Uses peer dependencies.

   • Good for projects that already use specific versions of embedding libraries.
   • Keeps your dependency tree lean if you only need specific embedding libraries.
   • Import with: const chroma = require("chromadb-client");

Both packages provide identical functionality and API.

File: clients/js/examples/README.md Copy Chapter

ChromaDB Examples

This directory contains examples for using both ChromaDB package options:

1. chromadb: Bundled package with all dependencies included
2. chromadb-client: Package with peer dependencies that you install separately

Node.js Example Copy Chapter

The Node.js example demonstrates how to use ChromaDB in a Node.js environment.

cd node
pnpm install

# Run with the default bundled package
pnpm dev

# Run with the bundled package explicitly
pnpm dev:bundled

# Run with the client package (peer dependencies)
pnpm dev:client

Browser Example Copy Chapter

The browser example demonstrates how to use ChromaDB in a browser environment.

cd browser
pnpm install

# Run with the default bundled package
pnpm dev

# Run with the bundled package explicitly
pnpm dev:bundled

# Run with the client package (peer dependencies)
pnpm dev:client

Differences Between Package Options Copy Chapter

• The bundled package (chromadb) includes all embedding libraries as dependencies, making it easier to get started.
• The client package (chromadb-client) uses peer dependencies, giving you more control over which versions of embedding libraries you use. It also keeps your dependency tree leaner if you only need specific embedding libraries.

Both packages offer identical functionality and API.

File: clients/js/packages/chromadb-core/src/generated/README.md Copy Chapter

API Copy Chapter

This generator creates TypeScript/JavaScript client that utilizes Fetch API. The generated Node module can be used in the following environments:

Environment

• Node.js
• Webpack
• Browserify

Language level

• ES5 - you must have a Promises/A+ library installed
• ES6

Module system

• CommonJS
• ES6 module system

It can be used in both TypeScript and JavaScript. In TypeScript, the definition should be automatically resolved via package.json. (Reference)

Building Copy Section

To build an compile the typescript sources to javascript use:

npm install
npm run build

Publishing Copy Section

First build the package then run npm publish

Consuming Copy Section

Navigate to the folder of your consuming project and run one of the following commands:

npm install PATH_TO_GENERATED_PACKAGE --save

File: clients/js/packages/chromadb-client/README.md Copy Chapter

ChromaDB Client

Chroma is the open-source data infrastructure for AI. Chroma makes it easy to build LLM apps by making knowledge, facts, and skills pluggable for LLMs.

Note: JS client version 3._ is only compatible with chromadb v1.0.6 and newer or Chroma Cloud. For prior version compatiblity, please use JS client version 2._.

This package provides embedding libraries as peer dependencies, allowing you to manage your own versions of embedding libraries and keep your dependency tree lean by not bundling dependencies you don't use. For a thick client with bundled embedding functions, install chromadb.

Features Copy Chapter

• ✅ Complete TypeScript support
• ✅ Embedding libraries as peer dependencies for a smaller package size
• ✅ Works in both Node.js and browser environments
• ✅ Only install the embedding libraries you need

Installation Copy Chapter

# npm
npm install chromadb-client

# pnpm
pnpm add chromadb-client

# yarn
yarn add chromadb-client

You'll need to install any required embedding libraries separately. For example:

# For OpenAI embeddings
npm install chromadb-client openai

# For default embeddings
npm install chromadb-client chromadb-default-embed

# For Cohere embeddings
npm install chromadb-client cohere-ai

Getting Started Copy Chapter

Chroma needs to be running in order for this client to talk to it. Please see the Usage Guide to learn how to quickly stand this up.

import { ChromaClient } from "chromadb-client";

// Initialize the client
const chroma = new ChromaClient({ path: "http://localhost:8000" });

// Create a collection
const collection = await chroma.createCollection({ name: "my-collection" });

// Add documents to the collection
await collection.add({
  ids: ["id1", "id2"],
  embeddings: [
    [1.1, 2.3, 3.2],
    [4.5, 6.9, 4.4],
  ],
  metadatas: [{ source: "doc1" }, { source: "doc2" }],
  documents: ["Document 1 content", "Document 2 content"],
});

// Query the collection
const results = await collection.query({
  queryEmbeddings: [1.1, 2.3, 3.2],
  nResults: 2,
});

Using Embedding Functions Copy Chapter

Make sure to install the necessary peer dependencies before using embedding functions:

// First install: npm install chromadb-client openai
import { ChromaClient, OpenAIEmbeddingFunction } from "chromadb-client";

const embedder = new OpenAIEmbeddingFunction({
  openai_api_key: "your-api-key",
  model_name: "text-embedding-ada-002",
});

const chroma = new ChromaClient({ path: "http://localhost:8000" });
const collection = await chroma.createCollection({
  name: "my-collection",
  embeddingFunction: embedder,
});

// Now you can add documents without providing embeddings
await collection.add({
  ids: ["id1"],
  documents: ["Document content"],
});

// And query with text
const results = await collection.query({
  queryTexts: ["similar document"],
  nResults: 2,
});

Available Embedding Functions Copy Chapter

This package supports multiple embedding providers as peer dependencies:

• OpenAI (openai)
• Cohere (cohere-ai)
• Default embeddings (chromadb-default-embed)
• Google Generative AI (@google/generative-ai)
• Xenova Transformers (@xenova/transformers)
• Voyage AI (voyageai)
• Ollama (ollama)

Why choose chromadb-client? Copy Chapter

• Smaller package size: Only install the dependencies you need
• Flexible dependency versions: Manage your own versions of embedding libraries
• Less bloat: Ideal for production environments where you only use specific embedding providers
• Same functionality: Provides identical features as the main chromadb package

Additional Resources Copy Chapter

• 📖 Documentation
• 💬 Community Discord
• 🏠 Homepage
• GitHub Repository

License Copy Chapter

Apache 2.0

File: clients/js/packages/chromadb/README.md Copy Chapter

ChromaDB JavaScript Client

Chroma is the open-source data infrastructure for AI. Chroma makes it easy to build LLM apps by making knowledge, facts, and skills pluggable for LLMs.

This package includes all embedding libraries as bundled dependencies, providing a simple installation experience without worrying about dependency management. For a thin client, install chromadb-client

Features Copy Chapter

• ✅ Complete TypeScript support
• ✅ All embedding libraries included as bundled dependencies
• ✅ Works in both Node.js and browser environments
• ✅ Simple installation with no peer dependency requirements

Installation Copy Chapter

# npm
npm install chromadb

# pnpm
pnpm add chromadb

# yarn
yarn add chromadb

Getting Started Copy Chapter

Chroma needs to be running in order for this client to talk to it. Please see the Usage Guide to learn how to quickly stand this up.

import { ChromaClient } from "chromadb";

// Initialize the client
const chroma = new ChromaClient({ path: "http://localhost:8000" });

// Create a collection
const collection = await chroma.createCollection({ name: "my-collection" });

// Add documents to the collection
await collection.add({
  ids: ["id1", "id2"],
  embeddings: [
    [1.1, 2.3, 3.2],
    [4.5, 6.9, 4.4],
  ],
  metadatas: [{ source: "doc1" }, { source: "doc2" }],
  documents: ["Document 1 content", "Document 2 content"],
});

// Query the collection
const results = await collection.query({
  queryEmbeddings: [1.1, 2.3, 3.2],
  nResults: 2,
});

Using Embedding Functions Copy Chapter

This package includes all embedding libraries as bundled dependencies, so you can use them directly:

import { ChromaClient, OpenAIEmbeddingFunction } from "chromadb";

const embedder = new OpenAIEmbeddingFunction({
  openai_api_key: "your-api-key",
  model_name: "text-embedding-ada-002",
});

const chroma = new ChromaClient({ path: "http://localhost:8000" });
const collection = await chroma.createCollection({
  name: "my-collection",
  embeddingFunction: embedder,
});

// Now you can add documents without providing embeddings
await collection.add({
  ids: ["id1"],
  documents: ["Document content"],
});

// And query with text
const results = await collection.query({
  queryTexts: ["similar document"],
  nResults: 2,
});

Additional Resources Copy Chapter

• 📖 Documentation
• 💬 Community Discord
• 🏠 Homepage
• GitHub Repository

License Copy Chapter

Apache 2.0

File: clients/js/README.md Copy Chapter

chromadb Copy Chapter

Chroma is the open-source data infrastructure for AI. Chroma makes it easy to build LLM apps by making knowledge, facts, and skills pluggable for LLMs.

This package gives you a JS/TS interface to talk to a backend Chroma DB over REST.

Note: JS client version 3._ is only compatible with chromadb v1.0.6 and newer or Chroma Cloud. For prior version compatibility, please use JS client version 2._.

Learn more about Chroma

• 💬 Community Discord
• 📖 Documentation
• 💡 Colab Example
• 🏠 Homepage

Package Options Copy Chapter

There are two packages available for using ChromaDB in your JavaScript/TypeScript projects:

1. chromadb: Includes all embedding libraries as bundled dependencies.

   • Use this if you want a simple installation without worrying about dependency management.
   • Install with: npm install chromadb or pnpm add chromadb

2. chromadb-client: Provides embedding libraries as peer dependencies.

   • Use this if you want to manage your own versions of embedding libraries, or embed outside of Chroma.
   • Keeps your dependency tree lean by not bundling dependencies you don't use.
   • Install with: npm install chromadb-client or pnpm add chromadb-client
   • You'll need to install any required embedding libraries separately, e.g., npm install chromadb-client chromadb-default-embed

Both packages provide identical functionality, differing only in how dependencies are managed.

Getting started Copy Chapter

Chroma needs to be running in order for this client to talk to it. Please see the 🧪 Usage Guide to learn how to quickly stand this up.

Small example Copy Chapter

import { ChromaClient } from "chromadb"; // or "chromadb-client"
const chroma = new ChromaClient({ path: "http://localhost:8000" });
const collection = await chroma.createCollection({ name: "test-from-js" });
for (let i = 0; i < 20; i++) {
  await collection.add({
    ids: ["test-id-" + i.toString()],
    embeddings: [1, 2, 3, 4, 5],
    documents: ["test"],
  });
}
const queryData = await collection.query({
  queryEmbeddings: [1, 2, 3, 4, 5],
  queryTexts: ["test"],
});

Local development Copy Chapter

View the Development Readme

License Copy Chapter

Apache 2.0

2. Official Technical Reference & Guides (chroma-core/docs) Copy Chapter

File: README.md Copy Chapter

Deprecated

The docs are now in a monorepo with the rest of the codebase.

Read the new readme here:

https://github.com/chroma-core/chroma/tree/main/docs/docs.trychroma.com

Chroma docs

These docs are built using Docusaurus 2

Installation Copy Section

$ yarn

Local Development Copy Section

$ yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build Copy Section

$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Generating Python Docs Copy Section

1. Have chroma as a sibling to the the docs dir, eg

/docs
/chroma

2. Update pydoc-markdown.yml if you need to expose more files other than Collection and Client

3. Run yarn gen-python

Deployment Copy Section

Vercel handles deploying main to https://docs.trychroma.com

Generating Javascript Docs Copy Section

1. Have chroma as a sibling to the the docs dir, eg

/docs
/chroma

2. Update scripts/jsDocs.sh, sidebar.json if you need to expose more files other than Collection and Client

3. Run yarn gen-js

File: docs/intro.md Copy Chapter

sidebar_position: 0 slug: / title: 🏡 Home hide_title: true Copy Chapter

Chroma

Chroma is the open-source embedding database. Chroma makes it easy to build LLM apps by making knowledge, facts, and skills pluggable for LLMs.

Chroma gives you the tools to:

• store embeddings and their metadata
• embed documents and queries
• search embeddings

Chroma prioritizes:

• simplicity and developer productivity
• analysis on top of search
• it also happens to be very quick

Chroma consists of a Python client SDK, JavaScript/TypeScript client SDK and a server application. Check out the Colab demo.(yes, it can run in a notebook 😄)

Chroma is licensed under Apache 2.0

Python Copy Section

In Python, Chroma can run in-memory or in client/server (in alpha) mode.

pip install chromadb

JavaScript Copy Section

In JavaScript, Chroma runs in client/server mode and talks to a Python backend.

npm install --save chromadb # yarn add chromadb

Continue with the full getting started guide.

🔑 Getting started
🧪 Usage Guide
🧬 Embeddings
📄 API Reference
👽 About

💬 Join Community Discord
@trychroma

Language Support Copy Section

We welcome contributions for other languages!

Learn more on the Community Discord.

File: docs/getting-started.md Copy Chapter

sidebar_position: 2 title: "🔑 Getting Started" Copy Chapter

🔑 Getting started

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Select a language

Chroma is a database for building AI applications with embeddings. It comes with everything you need to get started built in, and runs on your machine. A hosted version is coming soon!

1. Install Copy Section

pip install chromadb

npm install --save chromadb # yarn add chromadb

pip install chromadb

2. Get the Chroma Client Copy Section

import chromadb
chroma_client = chromadb.Client()

chroma run --path /db_path

// CJS
const { ChromaClient } = require("chromadb");

// ESM
import { ChromaClient } from 'chromadb'

const client = new ChromaClient();

3. Create a collection Copy Section

Collections are where you'll store your embeddings, documents, and any additional metadata. You can create a collection with a name:

collection = chroma_client.create_collection(name="my_collection")

// CJS
const { OpenAIEmbeddingFunction } = require("chromadb");

// ESM
import { OpenAIEmbeddingFunction } from 'chromadb'

const embedder = new OpenAIEmbeddingFunction({
  openai_api_key: "your_api_key",
});
const collection = await client.createCollection({
  name: "my_collection",
  embeddingFunction: embedder,
});

4. Add some text documents to the collection Copy Section

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

await collection.add({
  ids: ["id1", "id2"],
  metadatas: [{ source: "my_source" }, { source: "my_source" }],
  documents: ["This is a document", "This is another document"],
});

If you have already generated embeddings yourself, you can load them directly in:

collection.add(
    embeddings=[[1.2, 2.3, 4.5], [6.7, 8.2, 9.2]],
    documents=["This is a document", "This is another document"],
    metadatas=[{"source": "my_source"}, {"source": "my_source"}],
    ids=["id1", "id2"]
)

await collection.add({
  ids: ["id1", "id2"],
  embeddings: [
    [1.2, 2.3, 4.5],
    [6.7, 8.2, 9.2],
  ],
  metadatas: [{ source: "my_source" }, { source: "my_source" }],
  documents: ["This is a document", "This is another document"],
});

5. Query the collection Copy Section

You can query the collection with a list of query texts, and Chroma will return the n most similar results. It's that easy!

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

const results = await collection.query({
  nResults: 2,
  queryTexts: ["This is a query document"],
});

📚 Next steps Copy Chapter

• Chroma is designed to be simple enough to get started with quickly and flexible enough to meet many use-cases. You can use your own embedding models, query Chroma with your own embeddings, and filter on metadata. To learn more about Chroma, check out the Usage Guide and API Reference.
• Chroma is integrated in LangChain (python and js), making it easy to build AI applications with Chroma. Check out the integrations page to learn more.
• You can deploy a persistent instance of Chroma to an external server, to make it easier to work on larger projects or with a team.

Coming Soon Copy Chapter

• A hosted version of Chroma, with an easy to use web UI and API
• Multiple datatypes, including images, audio, video, and more