chromadb

library1.5.5pypypi✓ verified 50d ago

Open-source embedded vector database for AI applications. Runs in-process (EphemeralClient, PersistentClient) or client-server mode (HttpClient). Handles embedding storage, metadata filtering, and similarity search. Supports pluggable embedding functions. Core backend rewritten in Rust in 1.x; also ships a lightweight HTTP-only client as the separate chromadb-client package.

vector-search database ai-ml llm-agents

pip install chromadb

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v1.5.9 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

6/12 runs

✓ 23.15s

py 3.11

6/12 runs

✓ 19.04s

py 3.12

6/12 runs

✓ 17.18s

py 3.13

6/12 runs

✓ 17.18s

py 3.9

6/12 runs

✓ 25.93s

437MB installed

● package 437MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

EphemeralClient

✓ from chromadb import EphemeralClient

✗ import chromadb client = chromadb.EphemeralClient()

PersistentClient

✓ from chromadb import PersistentClient

✗ import chromadb client = chromadb.PersistentClient(path="/db")

HttpClient

✓ from chromadb import HttpClient

✗ import chromadb client = chromadb.HttpClient(host="localhost", port=8000)

get_or_create_collection() is idempotent and preferred over create_collection() for most use cases. Python 3.9+ required — chromadb's telemetry dependency (posthog) fails silently on 3.8 with a misleading TypeError.

import sys if sys.version_info < (3, 9): raise RuntimeError("chromadb requires Python 3.9+. Current: " + sys.version) import chromadb # In-memory (prototyping) client = chromadb.EphemeralClient() # Persistent (local dev) # client = chromadb.PersistentClient(path="/path/to/db") collection = client.get_or_create_collection("my_docs") collection.add( documents=["This is doc one", "This is doc two"], ids=["id1", "id2"], ) results = collection.query( query_texts=["find something"], n_results=2, ) print(results)

chroma --version

Debug

Known issues

breakingchromadb.Client(Settings(...)) removed in 0.4.0. Enormous volume of tutorials, LangChain/LlamaIndex integration examples, and LLM-generated code still uses it. Raises AttributeError or TypeError on import.

fix

Replace with chromadb.EphemeralClient() (in-memory), chromadb.PersistentClient(path=...) (disk), or chromadb.HttpClient(host=..., port=...) (server). Old chroma_db_impl="duckdb+parquet" setting is gone entirely.

affects: < 0.4.0

breakingDatabase migrations between Chroma versions are irreversible. Upgrading the chromadb package upgrades on-disk data format. Downgrading after upgrade causes data loss or corruption.

fix

Back up PersistentClient data directory before upgrading. Use chroma utils migrate CLI if available for the version transition. Pin version in production: pip install chromadb==X.Y.Z.

affects: all

breakingServer CORS and auth configuration moved from environment variables to a YAML config file in the 1.x Rust-backed server. Environment variables like CHROMA_SERVER_CORS_ALLOW_ORIGINS and CHROMA_SERVER_AUTH_CREDENTIALS no longer work.

fix

Migrate server configuration to a chroma.yaml config file. See docs.trychroma.com/docs/overview/migration for the full config file schema.

affects: >= 1.0.0

gotchaDefault embedding function downloads ~200MB of model weights (all-MiniLM-L6-v2 via onnxruntime) on first call. First add() or query() call in a new environment hangs while downloading. No progress indicator.

fix

Pass embedding_function=None and provide embeddings= directly, or pre-download by calling the embedding function once explicitly before serving traffic. Use chromadb-client package if you never need local embedding.

affects: all

gotchaPersistentClient does not support concurrent access from multiple processes. SQLite-backed storage uses file locking. Multiple processes writing to the same path cause database corruption or blocked writes.

fix

For multi-process workloads, run chroma run --path ... as a server and connect all clients via HttpClient.

affects: all

gotchacollection.query() where= filter uses a specific operator syntax ($eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or). Plain dict equality {"key": "value"} is not valid — must be {"key": {"": "value"}}. Raises ValueError silently in old versions, error in new.

fix

Use explicit operator syntax for all metadata filters: where={"source": {"": "arxiv"}} not where={"source": "arxiv"}.

affects: all

gotchaTelemetry is enabled by default (sends anonymized usage data to PostHog). Runs on every client init.

fix

Disable with: chromadb.EphemeralClient(settings=Settings(anonymized_telemetry=False)) or set environment variable ANONYMIZED_TELEMETRY=False.

affects: all

breakingInstallation fails on Alpine Linux (musl-based distributions) due to missing C/C++ build tools and runtime libraries required by the Rust backend. Specifically, `libgcc_s.so.1` is not found and a `cc` linker is missing, leading to `subprocess.CalledProcessError` during package metadata preparation.

fix

On Alpine Linux, install the necessary build tools and C++ standard library: `apk add build-base libstdc++` before attempting to install chromadb.

affects: >= 1.0.0

Upgrade

Version history

1.5.9latest on PyPI

Audit

Dependencies

onnxruntimerequiredBundled for default embedding function (all-MiniLM-L6-v2). Pulls in ~200MB. Omit by passing your own embedding_function to create_collection().

tokenizersrequiredRequired for default embedding function. Same caveat as onnxruntime.

numpyrequiredRequired core dependency.

Agent activity

118 hits · last 30 days

node

bytedance

amazonbot

seranking-bot

ahrefsbot

applebot

oai-searchbot

Resources

githubhttps://github.com/chroma-core/chroma ↗

packagehttps://pypi.org/project/chromadb/ ↗

homepagehttps://trychroma.com ↗