0
# Configuration
1

2
ChromaDB provides a comprehensive configuration system for customizing behavior across authentication, server settings, storage, telemetry, and system components. Configuration can be set through environment variables, initialization parameters, or the global configure function.
3

4
## Capabilities
5

6
### Global Configuration
7

8
Set global configuration options that apply to all ChromaDB clients and operations.
9

10
```python { .api }
11
def configure(**kwargs) -> None:
12
    """
13
    Override Chroma's default settings, environment variables or .env files.
14
    
15
    Args:
16
        **kwargs: Configuration options as key-value pairs
17
    """
18

19
def get_settings() -> Settings:
20
    """
21
    Get the current global settings.
22
    
23
    Returns:
24
        Settings: Current configuration settings object
25
    """
26
```
27

28
**Usage Examples:**
29

30
```python
31
import chromadb
32

33
# Configure global settings
34
chromadb.configure(
35
    chroma_api_impl="chromadb.api.fastapi.FastAPI",
36
    chroma_server_host="localhost",
37
    chroma_server_http_port=8000,
38
    persist_directory="/path/to/data"
39
)
40

41
# Get current settings
42
settings = chromadb.get_settings()
43
print(f"Server host: {settings.chroma_server_host}")
44
print(f"Persist directory: {settings.persist_directory}")
45
```
46

47
### Settings Class
48

49
The Settings class provides comprehensive configuration options for all aspects of ChromaDB operation.
50

51
```python { .api }
52
class Settings:
53
    """ChromaDB configuration settings."""
54
    
55
    def __init__(self, **kwargs):
56
        """
57
        Initialize settings with configuration options.
58
        
59
        Common configuration options:
60
        
61
        # API Implementation
62
        chroma_api_impl: str = "chromadb.api.segment.SegmentAPI"
63
        
64
        # Server Configuration  
65
        chroma_server_host: str = "localhost"
66
        chroma_server_http_port: int = 8000
67
        chroma_server_ssl_enabled: bool = False
68
        chroma_server_headers: Optional[Dict[str, str]] = None
69
        
70
        # Storage Configuration
71
        persist_directory: Optional[str] = None
72
        is_persistent: bool = False
73
        allow_reset: bool = False
74
        
75
        # Authentication
76
        chroma_client_auth_provider: Optional[str] = None
77
        chroma_client_auth_credentials: Optional[str] = None
78
        chroma_auth_token_transport_header: Optional[str] = None
79
        
80
        # Telemetry
81
        anonymized_telemetry: bool = True
82
        
83
        # Performance
84
        chroma_segment_cache_policy: str = "LRU"
85
        chroma_segment_cache_max_size_bytes: int = 1024 * 1024 * 1024  # 1GB
86
        
87
        # System Components
88
        chroma_collection_assignment_policy: str = "chromadb.ingest.impl.simple.SimpleAssignmentPolicy"
89
        
90
        Args:
91
            **kwargs: Configuration key-value pairs
92
        """
93
```
94

95
### API Implementation Configuration
96

97
Configure which ChromaDB API implementation to use for different deployment scenarios.
98

99
**Configuration Options:**
100

101
```python
102
# Local segment-based API (default)
103
chroma_api_impl = "chromadb.api.segment.SegmentAPI"
104

105
# FastAPI server implementation
106
chroma_api_impl = "chromadb.api.fastapi.FastAPI"
107

108
# Async FastAPI implementation
109
chroma_api_impl = "chromadb.api.async_fastapi.AsyncFastAPI"
110

111
# Rust-backed implementation
112
chroma_api_impl = "chromadb.api.rust.RustBindingsAPI"
113
```
114

115
**Usage Examples:**
116

117
```python
118
from chromadb.config import Settings
119

120
# Configure for local persistent storage
121
settings = Settings(
122
    chroma_api_impl="chromadb.api.segment.SegmentAPI",
123
    persist_directory="/data/chromadb",
124
    is_persistent=True
125
)
126

127
client = chromadb.Client(settings=settings)
128
```
129

130
### Server Configuration
131

132
Configure connection parameters for remote ChromaDB servers.
133

134
```python { .api }
135
# Server connection settings
136
chroma_server_host: str = "localhost"
137
chroma_server_http_port: int = 8000
138
chroma_server_ssl_enabled: bool = False
139
chroma_server_headers: Optional[Dict[str, str]] = None
140
```
141

142
**Usage Examples:**
143

144
```python
145
# Configure for remote server with SSL
146
settings = Settings(
147
    chroma_api_impl="chromadb.api.fastapi.FastAPI",
148
    chroma_server_host="chroma.example.com",
149
    chroma_server_http_port=443,
150
    chroma_server_ssl_enabled=True,
151
    chroma_server_headers={
152
        "Authorization": "Bearer your-token",
153
        "Custom-Header": "custom-value"
154
    }
155
)
156

157
client = chromadb.Client(settings=settings)
158
```
159

160
### Storage Configuration
161

162
Configure data persistence and storage behavior.
163

164
```python { .api }
165
# Storage settings
166
persist_directory: Optional[str] = None  # Directory for persistent storage
167
is_persistent: bool = False              # Enable persistence
168
allow_reset: bool = False                # Allow database reset operations
169
```
170

171
**Usage Examples:**
172

173
```python
174
# Configure persistent storage
175
settings = Settings(
176
    persist_directory="/var/lib/chromadb",
177
    is_persistent=True,
178
    allow_reset=False  # Disable reset for safety
179
)
180

181
# Configure in-memory storage
182
settings = Settings(
183
    is_persistent=False,
184
    allow_reset=True  # Allow reset for testing
185
)
186
```
187

188
### Authentication Configuration
189

190
Configure authentication providers and credentials for secure deployments.
191

192
```python { .api }
193
# Authentication settings
194
chroma_client_auth_provider: Optional[str] = None
195
chroma_client_auth_credentials: Optional[str] = None
196
chroma_auth_token_transport_header: Optional[str] = None
197
chroma_overwrite_singleton_tenant_database_access_from_auth: bool = False
198
```
199

200
**Usage Examples:**
201

202
```python
203
from chromadb.auth.token_authn import TokenTransportHeader
204

205
# Configure token authentication
206
settings = Settings(
207
    chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider",
208
    chroma_client_auth_credentials="your-auth-token",
209
    chroma_auth_token_transport_header=TokenTransportHeader.X_CHROMA_TOKEN,
210
    chroma_overwrite_singleton_tenant_database_access_from_auth=True
211
)
212

213
client = chromadb.Client(settings=settings)
214
```
215

216
### Telemetry Configuration
217

218
Configure telemetry and monitoring settings.
219

220
```python { .api }
221
# Telemetry settings
222
anonymized_telemetry: bool = True
223
chroma_telemetry_impl: str = "chromadb.telemetry.posthog.Posthog"
224
```
225

226
**Usage Examples:**
227

228
```python
229
# Disable telemetry
230
settings = Settings(anonymized_telemetry=False)
231

232
# Custom telemetry implementation
233
settings = Settings(
234
    chroma_telemetry_impl="your.custom.telemetry.Implementation"
235
)
236
```
237

238
### Performance Configuration
239

240
Configure caching, batching, and performance-related settings.
241

242
```python { .api }
243
# Performance settings
244
chroma_segment_cache_policy: str = "LRU"
245
chroma_segment_cache_max_size_bytes: int = 1024 * 1024 * 1024  # 1GB
246
chroma_collection_assignment_policy: str = "chromadb.ingest.impl.simple.SimpleAssignmentPolicy"
247
```
248

249
### Environment Variables
250

251
ChromaDB settings can be configured through environment variables using the `CHROMA_` prefix.
252

253
**Common Environment Variables:**
254

255
```bash
256
# Server configuration
257
export CHROMA_SERVER_HOST="localhost"
258
export CHROMA_SERVER_HTTP_PORT="8000"
259
export CHROMA_SERVER_SSL_ENABLED="false"
260

261
# Storage configuration
262
export CHROMA_PERSIST_DIRECTORY="/data/chromadb"
263
export CHROMA_IS_PERSISTENT="true"
264

265
# Authentication
266
export CHROMA_CLIENT_AUTH_PROVIDER="chromadb.auth.token_authn.TokenAuthClientProvider"
267
export CHROMA_CLIENT_AUTH_CREDENTIALS="your-token"
268

269
# Cloud client
270
export CHROMA_API_KEY="your-cloud-api-key"
271
export CHROMA_TENANT="your-tenant"
272
export CHROMA_DATABASE="your-database"
273

274
# Telemetry
275
export CHROMA_ANONYMIZED_TELEMETRY="false"
276
```
277

278
### Multi-tenancy Configuration
279

280
Configure tenant and database settings for multi-tenant deployments.
281

282
```python { .api }
283
# Default tenant and database constants
284
DEFAULT_TENANT: str = "default_tenant"
285
DEFAULT_DATABASE: str = "default_database"
286
```
287

288
**Usage Examples:**
289

290
```python
291
# Create client with specific tenant/database
292
client = chromadb.Client(
293
    tenant="organization_a",
294
    database="production_db"
295
)
296

297
# Switch tenant/database on existing client
298
client.set_tenant("organization_b", database="staging_db")
299
client.set_database("development_db")
300
```
301

302
### Component System Configuration
303

304
Configure the dependency injection system and component implementations.
305

306
```python { .api }
307
class Component:
308
    """Base class for ChromaDB system components."""
309
    
310
class System:
311
    """Dependency injection system for ChromaDB components."""
312
    
313
    def instance(self, type_class: type) -> Any:
314
        """Get or create component instance."""
315
        
316
    def reset_state(self) -> None:
317
        """Reset system state."""
318
```
319

320
## Types
321

322
```python { .api }
323
from typing import Dict, Optional, Any, Union
324
from pathlib import Path
325

326
class Settings:
327
    """ChromaDB configuration settings class."""
328
    
329
    # API Implementation
330
    chroma_api_impl: str
331
    
332
    # Server Configuration
333
    chroma_server_host: str
334
    chroma_server_http_port: int
335
    chroma_server_ssl_enabled: bool
336
    chroma_server_headers: Optional[Dict[str, str]]
337
    
338
    # Storage Configuration
339
    persist_directory: Optional[Union[str, Path]]
340
    is_persistent: bool
341
    allow_reset: bool
342
    
343
    # Authentication
344
    chroma_client_auth_provider: Optional[str]
345
    chroma_client_auth_credentials: Optional[str]
346
    chroma_auth_token_transport_header: Optional[str]
347
    
348
    # Telemetry
349
    anonymized_telemetry: bool
350
    chroma_telemetry_impl: str
351
    
352
    # Performance
353
    chroma_segment_cache_policy: str
354
    chroma_segment_cache_max_size_bytes: int
355
    
356
    def __init__(self, **kwargs): ...
357

358
# Constants
359
DEFAULT_TENANT: str = "default_tenant"
360
DEFAULT_DATABASE: str = "default_database"
361
```