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()

settings

Settings

Optional settings to override defaults.

tenant

str

default:"default_tenant"

Tenant name to use for requests.

database

str

default:"default_database"

Database name to use for requests.

return

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")

path

str | Path

default:"./chroma"

Directory to store persisted data.

settings

Settings

Optional settings to override defaults.

tenant

str

default:"default_tenant"

Tenant name to use for requests.

database

str

default:"default_database"

Database name to use for requests.

return

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)

host

str

default:"localhost"

Hostname of the Chroma server.

port

int

default:"8000"

HTTP port of the Chroma server.

ssl

bool

default:"false"

Whether to enable SSL for the connection.

headers

Dict[str, str]

Optional headers to send with each request.

settings

Settings

Optional settings to override defaults.

tenant

str

default:"default_tenant"

Tenant name to use for requests.

database

str

default:"default_database"

Database name to use for requests.

return

ClientAPI

A configured client instance connected to a Chroma server.

raises

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"
)

tenant

str

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

database

str

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

api_key

str

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

settings

Settings

Optional settings to override defaults.

return

ClientAPI

A configured client instance for Chroma Cloud.

raises

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())

host

str

default:"localhost"

Hostname of the Chroma server.

port

int

default:"8000"

HTTP port of the Chroma server.

ssl

bool

default:"false"

Whether to enable SSL for the connection.

headers

Dict[str, str]

Optional headers to send with each request.

settings

Settings

Optional settings to override defaults.

tenant

str

default:"default_tenant"

Tenant name to use for requests.

database

str

default:"default_database"

Database name to use for requests.

return

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:

path

str

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

settings

Settings

Optional settings to override defaults.

tenant

str

default:"default_tenant"

Tenant name to use for requests.

database

str

default:"default_database"

Database name to use for requests.

Returns:

return

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

Settings

required

Settings for connecting to the Chroma server.

Returns:

return

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:

return

Settings

The current global Settings object.

Collection Management

create_collection()

Create a new collection.

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

name

str

required

Collection name.

schema

Schema

Optional collection schema for indexes and encryption.

metadata

CollectionMetadata

Optional collection metadata.

embedding_function

EmbeddingFunction

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

data_loader

DataLoader

Optional data loader for documents with URIs.

get_or_create

bool

default:"false"

Whether to return an existing collection if present.

return

Collection

The created collection.

raises

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")

name

str

required

Collection name.

embedding_function

EmbeddingFunction

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

data_loader

DataLoader

Optional data loader for documents with URIs.

return

Collection

The requested collection.

raises

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"}
)

name

str

required

Collection name.

schema

Schema

Optional collection schema. Ignored if the collection already exists.

metadata

CollectionMetadata

Optional collection metadata. Ignored if the collection already exists.

embedding_function

EmbeddingFunction

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

data_loader

DataLoader

Optional data loader for URI-backed data.

return

Collection

The existing or newly created collection.

raises

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)

limit

int

Maximum number of collections to return.

offset

int

Number of collections to skip before returning.

return

Sequence[Collection]

Collection objects for the current tenant and database.

delete_collection()

Delete a collection by name.

client.delete_collection(name="my_collection")

name

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")

return

int

Server time in nanoseconds since epoch.

get_version()

Get the Chroma server version.

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

return

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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

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