Client API

The Client API provides the main entry point for interacting with Chroma. Use client constructors to create connections and client methods to manage collections.

Client Constructors

EphemeralClient()

Create an in-memory client for testing and development.

import chromadb

client = chromadb.EphemeralClient()

import chromadb
from chromadb.config import Settings

client = chromadb.EphemeralClient(
    settings=Settings(anonymized_telemetry=False)
)

Settings

Optional settings to override defaults.

str

default:"default_tenant"

Tenant name to use for requests.

str

default:"default_database"

Database name to use for requests.

ClientAPI

A configured client instance that stores all data in memory.

Data in EphemeralClient is not persisted to disk and will be lost when the client is closed.

PersistentClient()

Create a persistent client that stores data on disk.

import chromadb

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

import chromadb

with chromadb.PersistentClient(path="./chroma_data") as client:
    # Use client
    collection = client.get_or_create_collection("my_collection")
# Client is automatically closed

str | Path

default:"./chroma"

Directory to store persisted data.

Settings

Optional settings to override defaults.

str

default:"default_tenant"

Tenant name to use for requests.

str

default:"default_database"

Database name to use for requests.

ClientAPI

A configured client instance that persists data to disk.

For production use, prefer a server-backed Chroma instance using HttpClient() or CloudClient().

HttpClient()

Create a client that connects to a Chroma server over HTTP.

import chromadb

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

import chromadb

client = chromadb.HttpClient(
    host="chroma.example.com",
    port=443,
    ssl=True,
    headers={"Authorization": "Bearer token"}
)

str

default:"localhost"

Hostname of the Chroma server.

int

default:"8000"

HTTP port of the Chroma server.

bool

default:"false"

Whether to enable SSL for the connection.

Dict[str, str]

Optional headers to send with each request.

Settings

Optional settings to override defaults.

str

default:"default_tenant"

Tenant name to use for requests.

str

default:"default_database"

Database name to use for requests.

ClientAPI

A configured client instance connected to a Chroma server.

ValueError

If settings specify a different host or port.

CloudClient()

Create a client for Chroma Cloud.

import chromadb

client = chromadb.CloudClient(
    api_key="your-api-key"
)

import os
import chromadb

# Set environment variables:
# CHROMA_API_KEY=your-api-key
# CHROMA_TENANT=your-tenant
# CHROMA_DATABASE=your-database

client = chromadb.CloudClient()

import chromadb

client = chromadb.CloudClient(
    tenant="my-tenant",
    database="my-database",
    api_key="your-api-key"
)

str

Tenant name, or None to infer from CHROMA_TENANT environment variable.

str

Database name, or None to infer from CHROMA_DATABASE environment variable.

str

API key for Chroma Cloud. If not provided, inferred from CHROMA_API_KEY environment variable.

Settings

Optional settings to override defaults.

ClientAPI

A configured client instance for Chroma Cloud.

ValueError

If no API key is provided or available in the environment.

AsyncHttpClient()

Create an async client that connects to a Chroma HTTP server.

import chromadb
import asyncio

async def main():
    client = await chromadb.AsyncHttpClient(
        host="localhost",
        port=8000
    )
    # Use client...
    collections = await client.list_collections()

asyncio.run(main())

str

default:"localhost"

Hostname of the Chroma server.

int

default:"8000"

HTTP port of the Chroma server.

bool

default:"false"

Whether to enable SSL for the connection.

Dict[str, str]

Optional headers to send with each request.

Settings

Optional settings to override defaults.

str

default:"default_tenant"

Tenant name to use for requests.

str

default:"default_database"

Database name to use for requests.

AsyncClientAPI

A configured async client instance.

RustClient()

Create a client using Rust bindings for improved performance. Can be ephemeral or persistent.

This client uses the Rust implementation for better performance. It’s useful for testing and development but not recommended for production use.

import chromadb

# Ephemeral client (in-memory)
client = chromadb.RustClient()

# Persistent client
client = chromadb.RustClient(path="./chroma_data")

Parameters:

str

Optional directory to save Chroma’s data to. If None, the client is ephemeral (in-memory).

Settings

Optional settings to override defaults.

str

default:"default_tenant"

Tenant name to use for requests.

str

default:"default_database"

Database name to use for requests.

Returns:

ClientAPI

A configured Rust-backed client instance.

AdminClient()

Create an admin client for tenant and database management operations.

import chromadb
from chromadb.config import Settings

# Create admin client
admin_client = chromadb.AdminClient(
    settings=Settings(
        chroma_server_host="localhost",
        chroma_server_http_port=8000
    )
)

# Create a new tenant
admin_client.create_tenant(name="my_tenant")

# Create a database
admin_client.create_database(name="my_database", tenant="my_tenant")

# List tenants
tenants = admin_client.list_tenants()

Parameters:

Settings

required

Settings for connecting to the Chroma server.

Returns:

AdminAPI

An admin client for tenant and database management.

Admin Operations:

create_tenant(name) - Create a new tenant
get_tenant(name) - Get tenant information
list_tenants() - List all tenants
create_database(name, tenant) - Create a database in a tenant
get_database(name, tenant) - Get database information
list_databases(tenant) - List databases in a tenant

Global Configuration

configure()

Override Chroma’s default settings globally.

import chromadb

# Configure global settings
chromadb.configure(
    chroma_api_impl="chromadb.api.segment.SegmentAPI",
    chroma_server_host="localhost",
    chroma_server_http_port=8000
)

# All clients created after this will use these settings
client = chromadb.Client()

Parameters: Accepts any Settings parameter as a keyword argument. Common settings include:

chroma_api_impl - API implementation to use
chroma_server_host - Server hostname
chroma_server_http_port - Server port
anonymized_telemetry - Enable/disable telemetry

get_settings()

Get the current global settings.

import chromadb

settings = chromadb.get_settings()
print(settings.chroma_server_host)
print(settings.chroma_server_http_port)

Returns:

Settings

The current global Settings object.

Collection Management

create_collection()

Create a new collection.

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

collection = client.create_collection(
    name="my_collection",
    metadata={"description": "My documents"}
)

from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

embedding_fn = OpenAIEmbeddingFunction(api_key="your-key")

collection = client.create_collection(
    name="my_collection",
    embedding_function=embedding_fn
)

from chromadb import Schema, VectorIndexConfig, HnswIndexConfig

schema = Schema()
schema.create_index(
    config=VectorIndexConfig(
        space="cosine",
        hnsw=HnswIndexConfig(ef_construction=200)
    )
)

collection = client.create_collection(
    name="my_collection",
    schema=schema
)

str

required

Collection name.

Schema

Optional collection schema for indexes and encryption.

CollectionMetadata

Optional collection metadata.

EmbeddingFunction

Optional embedding function for the collection. Defaults to DefaultEmbeddingFunction().

DataLoader

Optional data loader for documents with URIs.

bool

default:"false"

Whether to return an existing collection if present.

Collection

The created collection.

ValueError

If the collection already exists (when get_or_create=False) or if the embedding function conflicts with configuration.

get_collection()

Get an existing collection by name.

collection = client.get_collection(name="my_collection")

str

required

Collection name.

EmbeddingFunction

Optional embedding function for the collection. Defaults to DefaultEmbeddingFunction().

DataLoader

Optional data loader for documents with URIs.

Collection

The requested collection.

ValueError

If the collection does not exist or if the embedding function conflicts with configuration.

get_or_create_collection()

Get an existing collection or create a new one.

collection = client.get_or_create_collection(
    name="my_collection",
    metadata={"description": "My documents"}
)

str

required

Collection name.

Schema

Optional collection schema. Ignored if the collection already exists.

CollectionMetadata

Optional collection metadata. Ignored if the collection already exists.

EmbeddingFunction

Optional embedding function for the collection. Defaults to DefaultEmbeddingFunction().

DataLoader

Optional data loader for URI-backed data.

Collection

The existing or newly created collection.

ValueError

If the embedding function does not match the collection’s embedding function.

If the collection already exists, the schema, metadata arguments are ignored.

list_collections()

List all collections in the current database.

collections = client.list_collections()
for collection in collections:
    print(collection.name)

collections = client.list_collections(limit=10, offset=0)

int

Maximum number of collections to return.

int

Number of collections to skip before returning.

Sequence[Collection]

Collection objects for the current tenant and database.

delete_collection()

Delete a collection by name.

client.delete_collection(name="my_collection")

str

required

Collection name to delete.

This operation is irreversible. All data in the collection will be permanently deleted.

Client Utilities

heartbeat()

Check if the server is running and return the server time.

server_time = client.heartbeat()
print(f"Server time: {server_time} nanoseconds since epoch")

int

Server time in nanoseconds since epoch.

get_version()

Get the Chroma server version.

version = client.get_version()
print(f"Chroma version: {version}")

str

The Chroma version string.

close()

Close the client and release all resources.

client.close()

This is particularly important for PersistentClient to avoid SQLite file locking issues. Use context managers (with statement) for automatic cleanup.

Settings

Configure Chroma behavior with Settings.

from chromadb.config import Settings

settings = Settings(
    anonymized_telemetry=False,
    allow_reset=True
)

client = chromadb.Client(settings=settings)

Common Settings

anonymized_telemetry (bool): Enable/disable anonymized telemetry. Default: True
allow_reset (bool): Allow resetting the database. Default: False
chroma_server_host (str): Chroma server hostname
chroma_server_http_port (int): Chroma server HTTP port
chroma_server_ssl_enabled (bool): Enable SSL for server connections
chroma_server_headers (Dict[str, str]): Headers to send with requests
persist_directory (str): Directory for persistent storage
is_persistent (bool): Enable persistence

Settings can also be configured via environment variables. See the Configuration guide for details.

Python Client

JavaScript Client

Go Client

CLI

Client Constructors

EphemeralClient()

PersistentClient()

HttpClient()

CloudClient()

AsyncHttpClient()

RustClient()

AdminClient()

Global Configuration

configure()

get_settings()

Collection Management

create_collection()

get_collection()

get_or_create_collection()

list_collections()

delete_collection()

Client Utilities

heartbeat()

get_version()

close()

Settings

Common Settings

​Client Constructors

​EphemeralClient()

​PersistentClient()

​HttpClient()

​CloudClient()

​AsyncHttpClient()

​RustClient()

​AdminClient()

​Global Configuration

​configure()

​get_settings()

​Collection Management

​create_collection()

​get_collection()

​get_or_create_collection()

​list_collections()

​delete_collection()

​Client Utilities

​heartbeat()

​get_version()

​close()

​Settings

​Common Settings

Client Constructors

EphemeralClient()

PersistentClient()

HttpClient()

CloudClient()

AsyncHttpClient()

RustClient()

AdminClient()

Global Configuration

configure()

get_settings()

Collection Management

create_collection()

get_collection()

get_or_create_collection()

list_collections()

delete_collection()

Client Utilities

heartbeat()

get_version()

close()

Settings

Common Settings