Installation

Chroma is available as a package for Python, JavaScript, and Go. You can also run it in Docker or build from source.

Python

Requirements

Python 3.9 or higher
SQLite 3.35.0 or higher (automatically handled on most systems)

Install via pip

pip install chromadb

# Install with additional dependencies for development
pip install chromadb[dev]

Verify Installation

import chromadb
print(chromadb.__version__)  # Should print: 1.5.2

client = chromadb.Client()
print("Chroma is working!")

SQLite Version Issue: Chroma requires SQLite 3.35.0 or higher. If you encounter an error about SQLite version:

Google Colab: Automatically handled with pysqlite3-binary
Other systems: Visit Troubleshooting SQLite for upgrade instructions

Python Client Types

Chroma provides several client types for different use cases:

EphemeralClient
PersistentClient
HttpClient
CloudClient

In-memory client that doesn’t persist data. Perfect for testing.

import chromadb

client = chromadb.EphemeralClient()
# or simply
client = chromadb.Client()

Stores data on disk for local development.

import chromadb

client = chromadb.PersistentClient(path="./chroma_data")

Connect to a remote Chroma server.

import chromadb

client = chromadb.HttpClient(
    host="localhost",
    port=8000,
    ssl=False,
    headers={"Authorization": "Bearer token"}  # optional
)

Connect to Chroma Cloud (production-ready hosted service).

import chromadb

# API key can also be set via CHROMA_API_KEY environment variable
client = chromadb.CloudClient(
    tenant="my-tenant",      # or set CHROMA_TENANT
    database="my-database",  # or set CHROMA_DATABASE
    api_key="your-api-key"  # or set CHROMA_API_KEY
)

JavaScript

Requirements

Node.js 20 or higher

Install via npm

npm install chromadb

yarn add chromadb

pnpm add chromadb

Verify Installation

import { ChromaClient } from 'chromadb';

const client = new ChromaClient();
console.log('Chroma is working!');

The JavaScript client (version 3.3.1) includes optional native bindings for better performance on supported platforms:

macOS (ARM64 and x64)
Linux (ARM64 and x64)
Windows (x64 and ARM64)

JavaScript Client Types

In-Memory
HTTP Client

In-memory client for testing and development.

import { ChromaClient } from 'chromadb';

const client = new ChromaClient();

Connect to a remote Chroma server.

import { ChromaClient } from 'chromadb';

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

Go

Requirements

Go 1.23.0 or higher

Install via go get

go get github.com/chroma-core/chroma/go

Usage

import "github.com/chroma-core/chroma/go"

// Your Go code here

The Go client is part of the Chroma server implementation. For client-side usage, consider using the HTTP API with a Go HTTP client.

Docker

Using Pre-built Image

The easiest way to run Chroma server is using the official Docker image:

Pull the Image

docker pull ghcr.io/chroma-core/chroma:latest

Run the Container

docker run -p 8000:8000 ghcr.io/chroma-core/chroma:latest

Verify It's Running

curl http://localhost:8000/api/v2/heartbeat

Using Docker Compose

For persistent storage, use Docker Compose:

version: '3.9'

networks:
  net:
    driver: bridge

services:
  server:
    image: ghcr.io/chroma-core/chroma:latest
    environment:
      - IS_PERSISTENT=TRUE
    volumes:
      - chroma-data:/chroma/chroma/
    ports:
      - 8000:8000
    networks:
      - net

volumes:
  chroma-data:
    driver: local

version: '3.9'

networks:
  net:
    driver: bridge

services:
  server:
    image: ghcr.io/chroma-core/chroma:latest
    volumes:
      - chroma-data:/data
    environment:
      - CHROMA_OPEN_TELEMETRY__ENDPOINT=${CHROMA_OPEN_TELEMETRY__ENDPOINT}
      - CHROMA_OPEN_TELEMETRY__SERVICE_NAME=${CHROMA_OPEN_TELEMETRY__SERVICE_NAME}
      - OTEL_EXPORTER_OTLP_HEADERS=${OTEL_EXPORTER_OTLP_HEADERS}
    restart: unless-stopped
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v2/heartbeat"]
      interval: 30s
      timeout: 10s
      retries: 3
    networks:
      - net

volumes:
  chroma-data:
    driver: local

Save as docker-compose.yml and run:

docker-compose up -d

Docker Configuration

Common environment variables:

IS_PERSISTENT=TRUE - Enable persistent storage
CHROMA_OPEN_TELEMETRY__ENDPOINT - OpenTelemetry endpoint for observability
CHROMA_OPEN_TELEMETRY__SERVICE_NAME - Service name for telemetry
OTEL_EXPORTER_OTLP_HEADERS - OTLP headers for authentication

Install from Source

For development or to build from source:

Clone the Repository

git clone https://github.com/chroma-core/chroma.git
cd chroma

Set Up Python Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Dependencies

pip install -r requirements.txt
pip install -r requirements_dev.txt

Install Pre-commit Hooks

pre-commit install

Install in Editable Mode

pip install -e .

Build Rust Bindings (Optional)

For development with Rust components:

# Install maturin
pip install maturin

# Build Rust bindings
maturin dev

Development Setup

For distributed Chroma development with Kubernetes:

Requirements:

Docker
Local Kubernetes cluster (OrbStack for macOS, Kind for Linux)
Tilt
Helm

# Start Kubernetes cluster (if using OrbStack, enable it in the UI)

# Start distributed Chroma
tilt up

# Access at http://localhost:8000
# View Tilt dashboard at http://localhost:10350

# Clean up
tilt down

Run the Server

Once installed, you can run the Chroma server:

chroma run --path /chroma_db_path

docker run -p 8000:8000 -v chroma-data:/data ghcr.io/chroma-core/chroma:latest

npx chroma run

The server will start on http://localhost:8000 by default.

Verify Installation

Test your installation by connecting to the server:

import chromadb

client = chromadb.HttpClient(host="localhost", port=8000)
print(client.heartbeat())  # Should return a timestamp

import { ChromaClient } from 'chromadb';

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

const heartbeat = await client.heartbeat();
console.log(heartbeat);  // Should return a timestamp

curl http://localhost:8000/api/v2/heartbeat

Troubleshooting

SQLite version error (Python)

If you see an error about SQLite version being too old:

# Install pysqlite3-binary
pip install pysqlite3-binary

For more details, see Troubleshooting SQLite.

Port already in use

If port 8000 is already in use:

# Use a different port
chroma run --port 8001

# Or in Docker
docker run -p 8001:8000 ghcr.io/chroma-core/chroma:latest

Connection refused

Make sure the Chroma server is running and accessible:

# Check if server is running
curl http://localhost:8000/api/v2/heartbeat

# Check Docker container logs
docker logs <container-id>

Native bindings not found (JavaScript)

The JavaScript client includes optional native bindings for better performance. If they fail to load, the client will fall back to a pure JavaScript implementation. This is normal and doesn’t affect functionality.

Next Steps

Quickstart

Get up and running with your first collection

Configuration

Configure Chroma for your use case

Deployment

Deploy Chroma to production

API Reference

Explore the full API documentation

Get Started

Core Concepts

Guides

Deployment

Operations

Python

Requirements

Install via pip

Verify Installation

Python Client Types

JavaScript

Requirements

Install via npm

Verify Installation

JavaScript Client Types

Go

Requirements

Install via go get

Usage

Docker

Using Pre-built Image

Using Docker Compose

Docker Configuration

Install from Source

Development Setup

Run the Server

Verify Installation

Troubleshooting

Next Steps

Quickstart

Configuration

Deployment

API Reference

​Python

​Requirements

​Install via pip

​Verify Installation

​Python Client Types

​JavaScript

​Requirements

​Install via npm

​Verify Installation

​JavaScript Client Types

​Go

​Requirements

​Install via go get

​Usage

​Docker

​Using Pre-built Image

​Using Docker Compose

​Docker Configuration

​Install from Source

​Development Setup

​Run the Server

​Verify Installation

​Troubleshooting

​Next Steps

Quickstart

Configuration

Deployment

API Reference

Python

Requirements

Install via pip

Verify Installation

Python Client Types

JavaScript

Requirements

Install via npm

Verify Installation

JavaScript Client Types

Go

Requirements

Install via go get

Usage

Docker

Using Pre-built Image

Using Docker Compose

Docker Configuration

Install from Source

Development Setup

Run the Server

Verify Installation

Troubleshooting

Next Steps