ChromaDB

Warnings

• breaking chromadb.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.
• breaking Database 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.
• breaking Server 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.
• gotcha Default 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.
• gotcha PersistentClient 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.
• gotcha collection.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"}.
• gotcha Telemetry 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.

Install

• pip install chromadb Full (includes server, embedding deps)
• pip install chromadb-client HTTP client only (lightweight, no server)

Imports

• EphemeralClient / PersistentClient / HttpClient

  import chromadb
  client = chromadb.EphemeralClient()  # in-memory
  client = chromadb.PersistentClient(path="/db")  # disk
  client = chromadb.HttpClient(host="localhost", port=8000)  # server

  Settings-based Client() init pattern removed in 0.4.0. All pre-0.4 tutorials use it. Causes TypeError or missing attribute errors on current versions.

Quickstart

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)