0
# Docker Compose
1

2
Complete Docker Compose support for multi-container application orchestration. Docker Compose enables defining and running multi-container applications using YAML configuration files.
3

4
## Capabilities
5

6
### Application Lifecycle Management
7

8
Start, stop, and manage multi-container applications defined in Compose files.
9

10
```python { .api }
11
def up(
12
    services: Optional[List[str]] = None,
13
    *,
14
    detach: bool = False,
15
    build: bool = False,
16
    no_build: bool = False,
17
    pull: Optional[str] = None,
18
    no_deps: bool = False,
19
    force_recreate: bool = False,
20
    no_recreate: bool = False,
21
    no_start: bool = False,
22
    scale: Optional[Dict[str, int]] = None,
23
    abort_on_container_exit: bool = False,
24
    timeout: Optional[int] = None,
25
    remove_orphans: bool = False,
26
    profiles: Optional[List[str]] = None
27
) -> None:
28
    """
29
    Create and start containers for services.
30
    
31
    Parameters:
32
    - services: Specific services to start
33
    - detach: Run in background
34
    - build: Build images before starting
35
    - no_build: Don't build missing images
36
    - pull: Pull policy (always, missing, never)
37
    - no_deps: Don't start linked services
38
    - force_recreate: Recreate containers even if unchanged
39
    - no_recreate: Don't recreate existing containers
40
    - no_start: Don't start services after creating
41
    - scale: Service scaling (service_name: replica_count)
42
    - abort_on_container_exit: Stop all containers if any exits
43
    - timeout: Shutdown timeout in seconds
44
    - remove_orphans: Remove containers for services not in Compose file
45
    - profiles: Specify service profiles to enable
46
    """
47

48
def down(
49
    *,
50
    remove_orphans: bool = False,
51
    volumes: bool = False,
52
    rmi: Optional[str] = None,
53
    timeout: Optional[int] = None
54
) -> None:
55
    """
56
    Stop and remove containers and networks.
57
    
58
    Parameters:
59
    - remove_orphans: Remove containers for services not in Compose file
60
    - volumes: Remove named volumes and anonymous volumes
61
    - rmi: Remove images (all, local)
62
    - timeout: Shutdown timeout in seconds
63
    """
64

65
def start(services: Optional[List[str]] = None) -> None:
66
    """
67
    Start existing containers for services.
68
    
69
    Parameters:
70
    - services: Specific services to start
71
    """
72

73
def stop(
74
    services: Optional[List[str]] = None,
75
    *,
76
    timeout: Optional[int] = None
77
) -> None:
78
    """
79
    Stop running containers without removing them.
80
    
81
    Parameters:
82
    - services: Specific services to stop
83
    - timeout: Shutdown timeout in seconds
84
    """
85

86
def restart(
87
    services: Optional[List[str]] = None,
88
    *,
89
    timeout: Optional[int] = None
90
) -> None:
91
    """
92
    Restart services.
93
    
94
    Parameters:
95
    - services: Specific services to restart
96
    - timeout: Shutdown timeout in seconds
97
    """
98
```
99

100
### Service Management
101

102
Pause, unpause, and scale services within Compose applications.
103

104
```python { .api }
105
def pause(services: Optional[List[str]] = None) -> None:
106
    """
107
    Pause services (suspend all processes).
108
    
109
    Parameters:
110
    - services: Specific services to pause
111
    """
112

113
def unpause(services: Optional[List[str]] = None) -> None:
114
    """
115
    Unpause services.
116
    
117
    Parameters:
118
    - services: Specific services to unpause
119
    """
120

121
def kill(
122
    services: Optional[List[str]] = None,
123
    *,
124
    signal: str = "SIGKILL"
125
) -> None:
126
    """
127
    Kill containers for services.
128
    
129
    Parameters:
130
    - services: Specific services to kill
131
    - signal: Signal to send
132
    """
133
```
134

135
### Build Operations
136

137
Build and rebuild images for Compose services.
138

139
```python { .api }
140
def build(
141
    services: Optional[List[str]] = None,
142
    *,
143
    build_args: Optional[Dict[str, str]] = None,
144
    no_cache: bool = False,
145
    pull: bool = False,
146
    parallel: bool = True,
147
    progress: str = "auto",
148
    quiet: bool = False
149
) -> None:
150
    """
151
    Build or rebuild services.
152
    
153
    Parameters:
154
    - services: Specific services to build
155
    - build_args: Build-time variables
156
    - no_cache: Don't use cache when building
157
    - pull: Always pull newer version of base image
158
    - parallel: Build images in parallel
159
    - progress: Progress output type (auto, plain, tty)
160
    - quiet: Don't print build output
161
    """
162
```
163

164
### Service Inspection and Monitoring
165

166
List services, view logs, and monitor service status.
167

168
```python { .api }
169
def ps(
170
    services: Optional[List[str]] = None,
171
    *,
172
    all: bool = False,
173
    filter: Optional[str] = None,
174
    format: Optional[str] = None,
175
    quiet: bool = False,
176
    services_filter: bool = False,
177
    status: Optional[List[str]] = None
178
) -> List[Container]:
179
    """
180
    List containers for services.
181
    
182
    Parameters:
183
    - services: Specific services to list
184
    - all: Show all containers (including stopped)
185
    - filter: Filter containers by state
186
    - format: Output format
187
    - quiet: Only show container IDs
188
    - services_filter: Show only services
189
    - status: Filter by container status
190
    
191
    Returns:
192
    - List of Container objects
193
    """
194

195
def logs(
196
    services: Optional[List[str]] = None,
197
    *,
198
    follow: bool = False,
199
    tail: Optional[int] = None,
200
    since: Optional[str] = None,
201
    until: Optional[str] = None,
202
    timestamps: bool = False,
203
    no_color: bool = False
204
) -> str:
205
    """
206
    View output from services.
207
    
208
    Parameters:
209
    - services: Specific services to show logs for
210
    - follow: Follow log output
211
    - tail: Number of lines from end of logs
212
    - since: Show logs since timestamp
213
    - until: Show logs until timestamp
214
    - timestamps: Show timestamps
215
    - no_color: Disable colored output
216
    
217
    Returns:
218
    - Log output string
219
    """
220

221
def top(services: Optional[List[str]] = None) -> Dict[str, List[Dict[str, str]]]:
222
    """
223
    Display running processes for services.
224
    
225
    Parameters:
226
    - services: Specific services to show processes for
227
    
228
    Returns:
229
    - Dictionary mapping service names to process lists
230
    """
231
```
232

233
### Configuration and Validation
234

235
View and validate Compose configurations.
236

237
```python { .api }
238
def config(
239
    *,
240
    resolve_image_digests: bool = False,
241
    no_interpolate: bool = False,
242
    quiet: bool = False,
243
    profiles: Optional[List[str]] = None,
244
    services: Optional[List[str]] = None,
245
    volumes: bool = False,
246
    hash: Optional[str] = None
247
) -> str:
248
    """
249
    Parse, resolve and render Compose file in canonical format.
250
    
251
    Parameters:
252
    - resolve_image_digests: Pin image tags to digests
253
    - no_interpolate: Don't interpolate environment variables
254
    - quiet: Only validate configuration
255
    - profiles: Specify service profiles to include
256
    - services: Print service names
257
    - volumes: Print volume names
258
    - hash: Print service config hash
259
    
260
    Returns:
261
    - Compose configuration as YAML string
262
    """
263

264
def version() -> Dict[str, str]:
265
    """
266
    Get Compose version information.
267
    
268
    Returns:
269
    - Version information dictionary
270
    """
271
```
272

273
### Container Operations
274

275
Execute commands and perform operations on service containers.
276

277
```python { .api }
278
def exec(
279
    service: str,
280
    command: List[str],
281
    *,
282
    detach: bool = False,
283
    interactive: bool = False,
284
    tty: bool = False,
285
    index: int = 1,
286
    user: Optional[str] = None,
287
    workdir: Optional[str] = None,
288
    env: Optional[Dict[str, str]] = None,
289
    privileged: bool = False
290
) -> str:
291
    """
292
    Execute command in running service container.
293
    
294
    Parameters:
295
    - service: Service name
296
    - command: Command to execute
297
    - detach: Run command in background
298
    - interactive: Keep STDIN open
299
    - tty: Allocate pseudo-TTY
300
    - index: Container index if service has multiple replicas
301
    - user: User to run command as
302
    - workdir: Working directory
303
    - env: Environment variables
304
    - privileged: Run with extended privileges
305
    
306
    Returns:
307
    - Command output (if not detached)
308
    """
309

310
def run(
311
    service: str,
312
    command: Optional[List[str]] = None,
313
    *,
314
    detach: bool = False,
315
    name: Optional[str] = None,
316
    entrypoint: Optional[str] = None,
317
    env: Optional[Dict[str, str]] = None,
318
    labels: Optional[Dict[str, str]] = None,
319
    user: Optional[str] = None,
320
    workdir: Optional[str] = None,
321
    ports: Optional[Dict[str, str]] = None,
322
    volumes: Optional[List[str]] = None,
323
    rm: bool = False,
324
    no_deps: bool = False,
325
    service_ports: bool = False,
326
    use_aliases: bool = False
327
) -> Union[str, Container]:
328
    """
329
    Run one-time commands for services.
330
    
331
    Parameters:
332
    - service: Service name
333
    - command: Command to run
334
    - detach: Run in background
335
    - name: Container name
336
    - entrypoint: Override entrypoint
337
    - env: Environment variables
338
    - labels: Container labels
339
    - user: User to run as
340
    - workdir: Working directory
341
    - ports: Port mappings
342
    - volumes: Volume mounts
343
    - rm: Remove container when done
344
    - no_deps: Don't start linked services
345
    - service_ports: Use service ports
346
    - use_aliases: Use service network aliases
347
    
348
    Returns:
349
    - Container object if detach=True, output string otherwise
350
    """
351
```
352

353
### Image and Volume Operations
354

355
Manage images and data associated with Compose services.
356

357
```python { .api }
358
def pull(
359
    services: Optional[List[str]] = None,
360
    *,
361
    ignore_pull_failures: bool = False,
362
    parallel: bool = True,
363
    quiet: bool = False,
364
    include_deps: bool = True
365
) -> None:
366
    """
367
    Pull service images.
368
    
369
    Parameters:
370
    - services: Specific services to pull
371
    - ignore_pull_failures: Continue with other services on failure
372
    - parallel: Pull images in parallel
373
    - quiet: Don't print progress
374
    - include_deps: Pull images for dependencies
375
    """
376

377
def push(
378
    services: Optional[List[str]] = None,
379
    *,
380
    ignore_push_failures: bool = False
381
) -> None:
382
    """
383
    Push service images to registry.
384
    
385
    Parameters:
386
    - services: Specific services to push
387
    - ignore_push_failures: Continue with other services on failure
388
    """
389

390
def images(
391
    services: Optional[List[str]] = None,
392
    *,
393
    quiet: bool = False
394
) -> List[Image]:
395
    """
396
    List images used by services.
397
    
398
    Parameters:
399
    - services: Specific services to list images for
400
    - quiet: Only show image IDs
401
    
402
    Returns:
403
    - List of Image objects
404
    """
405
```
406

407
### Cleanup Operations
408

409
Remove containers, networks, and other resources.
410

411
```python { .api }
412
def rm(
413
    services: Optional[List[str]] = None,
414
    *,
415
    stop: bool = False,
416
    force: bool = False,
417
    volumes: bool = False
418
) -> None:
419
    """
420
    Remove stopped service containers.
421
    
422
    Parameters:
423
    - services: Specific services to remove containers for
424
    - stop: Stop containers before removing
425
    - force: Force removal of running containers
426
    - volumes: Remove associated volumes
427
    """
428

429
def create(
430
    services: Optional[List[str]] = None,
431
    *,
432
    build: bool = False,
433
    no_build: bool = False,
434
    pull: Optional[str] = None,
435
    force_recreate: bool = False,
436
    no_recreate: bool = False
437
) -> None:
438
    """
439
    Create services without starting them.
440
    
441
    Parameters:
442
    - services: Specific services to create
443
    - build: Build images before creating
444
    - no_build: Don't build missing images
445
    - pull: Pull policy (always, missing, never)
446
    - force_recreate: Recreate containers even if unchanged
447
    - no_recreate: Don't recreate existing containers
448
    """
449
```
450

451
## Usage Examples
452

453
### Basic Compose Operations
454

455
```python
456
from python_on_whales import docker
457

458
# Start all services
459
docker.compose.up(detach=True)
460

461
# View service status
462
containers = docker.compose.ps()
463
for container in containers:
464
    print(f"Service: {container.name} - Status: {container.status}")
465

466
# View logs
467
logs = docker.compose.logs(services=["web"], tail=50)
468
print(logs)
469

470
# Scale a service
471
docker.compose.up(scale={"web": 3})
472

473
# Stop and remove everything
474
docker.compose.down(volumes=True)
475
```
476

477
### Development Workflow
478

479
```python
480
# Build and start with live reload
481
docker.compose.up(build=True, detach=True)
482

483
# Execute commands in service containers
484
result = docker.compose.exec(
485
    "web",
486
    ["python", "manage.py", "migrate"],
487
    interactive=True,
488
    tty=True
489
)
490

491
# View configuration
492
config = docker.compose.config()
493
print(config)
494

495
# Restart specific service
496
docker.compose.restart(services=["web"])
497
```
498

499
## Types
500

501
```python { .api }
502
class ComposeProject:
503
    name: str
504
    services: List[str]
505
    config_files: List[str]
506
    
507
class ComposeService:
508
    name: str
509
    image: str
510
    ports: List[str]
511
    volumes: List[str]
512
    environment: Dict[str, str]
513
    depends_on: List[str]
514
    
515
class ComposeConfig:
516
    version: str
517
    services: Dict[str, ComposeService]
518
    networks: Dict[str, Dict[str, Any]]
519
    volumes: Dict[str, Dict[str, Any]]
520
```