0
# Python-on-Whales
1

2
A comprehensive Python client library for Docker that makes container management intuitive and fun. Python-on-whales provides a Pythonic interface that mirrors Docker CLI commands, enabling developers to perform all Docker operations programmatically including running containers, building images, managing volumes, and orchestrating multi-container applications with Docker Compose.
3

4
## Package Information
5

6
- **Package Name**: python-on-whales
7
- **Language**: Python
8
- **Installation**: `pip install python-on-whales`
9

10
## Core Imports
11

12
```python
13
import python_on_whales
14
```
15

16
Standard usage patterns:
17

18
```python
19
from python_on_whales import docker
20
```
21

22
For specific components:
23

24
```python
25
from python_on_whales import (
26
    DockerClient, Container, Image, Volume, Network, Builder,
27
    Config, Context, DockerContextConfig, KubernetesContextConfig,
28
    Node, Plugin, Pod, Secret, Service, Stack, Task, ManifestList,
29
    ContainerStats, SystemInfo, Version, DockerException, ClientNotFoundError
30
)
31
```
32

33
## Basic Usage
34

35
```python
36
from python_on_whales import docker
37

38
# Run a simple container
39
result = docker.run("hello-world")
40
print(result)
41

42
# Run container with options
43
output = docker.run(
44
    "ubuntu:20.04", 
45
    ["echo", "Hello from container"], 
46
    remove=True
47
)
48
print(output)
49

50
# List running containers
51
containers = docker.ps()
52
for container in containers:
53
    print(f"Container: {container.name} - Status: {container.state}")
54

55
# Pull and manage images
56
docker.pull("python:3.9")
57
images = docker.images()
58
for image in images:
59
    print(f"Image: {image.repo_tags}")
60

61
# Work with volumes
62
volume = docker.volume.create("my-volume")
63
volumes = docker.volume.list()
64
```
65

66
## Architecture
67

68
Python-on-whales is built around a modular architecture that provides both high-level convenience and low-level control:
69

70
- **DockerClient**: Main interface providing access to all Docker functionality through component CLIs
71
- **Component CLIs**: Specialized interfaces for different Docker objects (containers, images, networks, etc.)
72
- **Object Models**: Pydantic-based models representing Docker objects with methods for operations and state management
73
- **Exception Handling**: Comprehensive error handling with specific exceptions for different failure scenarios
74
- **Backend Support**: Works with Docker, Podman, and other Docker-compatible clients
75

76
The library supports both synchronous operations and streaming for long-running commands, with extensive configuration options for different deployment scenarios.
77

78
## Capabilities
79

80
### Client Configuration
81

82
Main Docker client interface and configuration options for connecting to different Docker daemons, setting up contexts, and managing authentication.
83

84
```python { .api }
85
class DockerClient:
86
    def __init__(
87
        self,
88
        config: Optional[str] = None,
89
        context: Optional[str] = None,
90
        debug: bool = False,
91
        host: Optional[str] = None,
92
        log_level: str = "info",
93
        tls: bool = False,
94
        tlscacert: Optional[str] = None,
95
        compose_files: Optional[List[str]] = None,
96
        compose_profiles: Optional[List[str]] = None,
97
        compose_env_file: Optional[str] = None,
98
        compose_project_name: Optional[str] = None,
99
        compose_project_directory: Optional[str] = None,
100
        compose_compatibility: bool = False,
101
        client_call: Optional[List[str]] = None,
102
        client_type: str = "docker"
103
    ): ...
104
    
105
    def version(self) -> Version: ...
106
    def login(self, server: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None): ...
107
    def logout(self, server: Optional[str] = None): ...
108
```
109

110
[Client Configuration](./client.md)
111

112
### Container Operations
113

114
Comprehensive container lifecycle management including creation, execution, monitoring, and cleanup operations.
115

116
```python { .api }
117
def run(
118
    image: str,
119
    command: Optional[List[str]] = None,
120
    remove: bool = False,
121
    detach: bool = False,
122
    envs: Optional[Dict[str, str]] = None,
123
    volumes: Optional[List[str]] = None,
124
    ports: Optional[Dict[str, str]] = None,
125
    **kwargs
126
) -> Union[str, Container]: ...
127

128
def create(image: str, command: Optional[List[str]] = None, **kwargs) -> Container: ...
129
def ps(all: bool = False, filters: Optional[Dict[str, str]] = None) -> List[Container]: ...
130
def logs(container: str, follow: bool = False, tail: Optional[int] = None) -> str: ...
131
```
132

133
[Container Operations](./containers.md)
134

135
### Image Management
136

137
Image building, pulling, pushing, and management operations including legacy build and modern buildx support.
138

139
```python { .api }
140
def pull(image_name: str, platform: Optional[str] = None) -> Image: ...
141
def push(image_name: str) -> str: ...
142
def build(context_path: str, tags: Optional[List[str]] = None, **kwargs) -> Image: ...
143
def images(all: bool = False) -> List[Image]: ...
144
def remove(images: Union[str, List[str]], force: bool = False) -> None: ...
145
```
146

147
[Image Management](./images.md)
148

149
### Network Management
150

151
Docker network creation, management, and container connectivity operations.
152

153
```python { .api }
154
def create(name: str, driver: Optional[str] = None, **kwargs) -> Network: ...
155
def connect(network: str, container: str, **kwargs) -> None: ...
156
def disconnect(network: str, container: str, force: bool = False) -> None: ...
157
def list(filters: Optional[Dict[str, str]] = None) -> List[Network]: ...
158
```
159

160
[Network Management](./networks.md)
161

162
### Volume Management
163

164
Docker volume creation, management, and data persistence operations.
165

166
```python { .api }
167
def create(name: Optional[str] = None, driver: Optional[str] = None, **kwargs) -> Volume: ...
168
def list(filters: Optional[Dict[str, str]] = None) -> List[Volume]: ...
169
def remove(volumes: Union[str, List[str]], force: bool = False) -> None: ...
170
```
171

172
[Volume Management](./volumes.md)
173

174
### Docker Compose Integration
175

176
Complete Docker Compose support for multi-container application orchestration.
177

178
```python { .api }
179
def up(services: Optional[List[str]] = None, detach: bool = False, build: bool = False, **kwargs) -> None: ...
180
def down(remove_orphans: bool = False, volumes: bool = False, **kwargs) -> None: ...
181
def build(services: Optional[List[str]] = None, **kwargs) -> None: ...
182
def ps(services: Optional[List[str]] = None) -> List[Container]: ...
183
```
184

185
[Docker Compose](./compose.md)
186

187
### Build Operations
188

189
Advanced build operations using Docker Buildx for multi-platform builds and BuildKit features.
190

191
```python { .api }
192
def build(
193
    context_path: str,
194
    tags: Optional[List[str]] = None,
195
    platforms: Optional[List[str]] = None,
196
    push: bool = False,
197
    **kwargs
198
) -> Image: ...
199

200
def create(name: str, driver: Optional[str] = None, **kwargs) -> Builder: ...
201
```
202

203
[Build Operations](./build.md)
204

205
### System Operations
206

207
System-level Docker operations including information retrieval, cleanup, and monitoring.
208

209
```python { .api }
210
def info() -> SystemInfo: ...
211
def df() -> DiskFreeResult: ...
212
def prune(all: bool = False, volumes: bool = False) -> None: ...
213
def events(filters: Optional[Dict[str, str]] = None) -> Iterator[dict]: ...
214
```
215

216
[System Operations](./system.md)
217

218
### Swarm Management
219

220
Docker Swarm operations for container orchestration including nodes, services, secrets, and configs.
221

222
```python { .api }
223
def init(advertise_addr: Optional[str] = None, **kwargs) -> str: ...
224
def join(token: str, manager_addr: str, **kwargs) -> None: ...
225
def leave(force: bool = False) -> None: ...
226
```
227

228
[Swarm Management](./swarm.md)
229

230
### Config Management
231

232
Docker swarm configuration management for securely storing non-sensitive configuration data like application settings and template files.
233

234
```python { .api }
235
def create(
236
    name: str,
237
    file: Optional[str] = None,
238
    labels: Optional[Dict[str, str]] = None,
239
    template_driver: Optional[str] = None
240
) -> Config: ...
241

242
def inspect(x: Union[str, List[str]]) -> Union[Config, List[Config]]: ...
243
def list(filters: Optional[Dict[str, str]] = None) -> List[Config]: ...
244
def remove(x: Union[str, List[str]]) -> None: ...
245
```
246

247
[Config Management](./config.md)
248

249
### Context Management
250

251
Docker context management for switching between different Docker environments (local, remote, Kubernetes).
252

253
```python { .api }
254
def create(
255
    context_name: str,
256
    *,
257
    description: Optional[str] = None,
258
    docker: Optional[DockerContextConfig] = None,
259
    kubernetes: Optional[KubernetesContextConfig] = None
260
) -> Context: ...
261

262
def inspect(x: Optional[str] = None) -> Context: ...
263
def list() -> List[Context]: ...
264
def use(context: Union[str, Context]) -> None: ...
265
def remove(x: Union[str, List[str]], force: bool = False) -> None: ...
266
```
267

268
[Context Management](./context.md)
269

270
### Node Management
271

272
Docker swarm node management for controlling worker and manager nodes in a swarm cluster.
273

274
```python { .api }
275
def inspect(x: Union[str, List[str]]) -> Union[Node, List[Node]]: ...
276
def list() -> List[Node]: ...
277
def promote(x: Union[str, List[str]]) -> None: ...
278
def demote(x: Union[str, List[str]]) -> None: ...
279
def update(node: Union[str, Node], availability: Optional[str] = None, **kwargs) -> None: ...
280
def ps(x: Optional[Union[str, List[str]]] = None) -> List[Task]: ...
281
def remove(x: Union[str, List[str]], force: bool = False) -> None: ...
282
```
283

284
[Node Management](./node.md)
285

286
### Plugin Management
287

288
Docker plugin management for extending Docker functionality with third-party plugins.
289

290
```python { .api }
291
def install(plugin_name: str, **kwargs) -> Plugin: ...
292
def create(plugin_name: str, plugin_data_directory: str, compress: bool = False) -> Plugin: ...
293
def enable(plugin: Union[str, Plugin], timeout: Optional[int] = None) -> None: ...
294
def disable(plugin: Union[str, Plugin], force: bool = False) -> None: ...
295
def inspect(x: Union[str, List[str]]) -> Union[Plugin, List[Plugin]]: ...
296
def list() -> List[Plugin]: ...
297
def remove(x: Union[str, List[str]], force: bool = False) -> None: ...
298
```
299

300
[Plugin Management](./plugin.md)
301

302
### Pod Management
303

304
**Note: Podman-specific functionality**
305

306
Podman pod management for grouping containers with shared namespaces, networking, and storage.
307

308
```python { .api }
309
def create(name: Optional[str] = None, **kwargs) -> Pod: ...
310
def start(x: Union[str, List[str]]) -> None: ...
311
def stop(x: Union[str, List[str]], time: Optional[int] = None) -> None: ...
312
def restart(x: Union[str, List[str]]) -> None: ...
313
def pause(x: Union[str, List[str]]) -> None: ...
314
def unpause(x: Union[str, List[str]]) -> None: ...
315
def kill(x: Union[str, List[str]], signal: Optional[str] = None) -> None: ...
316
def inspect(x: Union[str, List[str]]) -> Union[Pod, List[Pod]]: ...
317
def list(filters: Sequence[str] = ()) -> List[Pod]: ...
318
def remove(x: Union[str, List[str]], force: bool = False, **kwargs) -> None: ...
319
```
320

321
[Pod Management](./pod.md)
322

323
### Secret Management
324

325
Docker swarm secret management for securely storing sensitive data like passwords, certificates, and API keys.
326

327
```python { .api }
328
def create(
329
    name: str,
330
    file: Optional[str] = None,
331
    driver: Optional[str] = None,
332
    labels: Optional[Dict[str, str]] = None
333
) -> Secret: ...
334

335
def inspect(x: Union[str, List[str]]) -> Union[Secret, List[Secret]]: ...
336
def list(filters: Sequence[str] = ()) -> List[Secret]: ...
337
def remove(x: Union[str, List[str]]) -> None: ...
338
```
339

340
[Secret Management](./secret.md)
341

342
### Service Management
343

344
Docker swarm service management for running and orchestrating containerized applications across multiple nodes.
345

346
```python { .api }
347
def create(image: str, command: Optional[List[str]] = None, **kwargs) -> Service: ...
348
def inspect(x: Union[str, List[str]]) -> Union[Service, List[Service]]: ...
349
def list(filters: Sequence[str] = ()) -> List[Service]: ...
350
def logs(service: Union[str, Service], **kwargs) -> Union[str, Iterable[Tuple[str, bytes]]]: ...
351
def ps(x: Union[str, List[str]]) -> List[Task]: ...
352
def update(service: Union[str, Service], **kwargs) -> None: ...
353
def scale(new_scales: Dict[str, int], detach: bool = False) -> None: ...
354
def remove(services: Union[str, List[str]]) -> None: ...
355
```
356

357
[Service Management](./service.md)
358

359
### Stack Management
360

361
Docker stack management for deploying multi-service applications using Docker Compose files in swarm mode.
362

363
```python { .api }
364
def deploy(name: str, compose_files: List[str], **kwargs) -> None: ...
365
def list() -> List[Stack]: ...
366
def services(stack: Union[str, Stack]) -> List[Service]: ...
367
def ps(x: Union[str, Stack]) -> List[Task]: ...
368
def remove(x: Union[str, List[str]]) -> None: ...
369
```
370

371
[Stack Management](./stack.md)
372

373
### Task Management
374

375
Docker swarm task inspection and monitoring for individual running instances of services on specific nodes.
376

377
```python { .api }
378
def list() -> List[Task]: ...
379
def inspect(x: Union[str, List[str]]) -> Union[Task, List[Task]]: ...
380
```
381

382
[Task Management](./task.md)
383

384
### Manifest Management
385

386
Docker manifest list management for multi-architecture image support.
387

388
```python { .api }
389
def create(name: str, manifests: List[str], **kwargs) -> ManifestList: ...
390
def annotate(name: str, manifest: str, **kwargs) -> None: ...
391
def inspect(x: Union[str, ManifestList]) -> ManifestList: ...
392
def push(x: Union[str, ManifestList], **kwargs) -> None: ...
393
def remove(manifest_lists: Union[str, List[str]]) -> None: ...
394
```
395

396
[Manifest Management](./manifest.md)
397

398
### Trust Management
399

400
**Note: Currently not implemented**
401

402
Docker Content Trust for image signing and verification (placeholder for future functionality).
403

404
```python { .api }
405
def inspect() -> None: ...  # Not implemented
406
def revoke() -> None: ...   # Not implemented  
407
def sign() -> None: ...     # Not implemented
408
```
409

410
[Trust Management](./trust.md)
411

412
## Types
413

414
```python { .api }
415
class Container:
416
    id: str
417
    name: str
418
    image: str
419
    state: str
420
    status: str
421
    ports: Dict[str, Any]
422
    mounts: List[Dict[str, Any]]
423
    
424
    def remove(self, force: bool = False, volumes: bool = False) -> None: ...
425
    def start(self) -> None: ...
426
    def stop(self, timeout: Optional[int] = None) -> None: ...
427
    def restart(self, timeout: Optional[int] = None) -> None: ...
428
    def kill(self, signal: str = "SIGKILL") -> None: ...
429
    def pause(self) -> None: ...
430
    def unpause(self) -> None: ...
431
    def logs(self, follow: bool = False, tail: Optional[int] = None) -> str: ...
432
    def execute(self, command: List[str], **kwargs) -> str: ...
433

434
class Image:
435
    id: str
436
    repo_tags: List[str]
437
    size: int
438
    created: str
439
    
440
    def remove(self, force: bool = False) -> None: ...
441
    def tag(self, repository: str, tag: Optional[str] = None) -> None: ...
442
    def save(self, output_path: str) -> None: ...
443

444
class Volume:
445
    name: str
446
    driver: str
447
    mountpoint: str
448
    
449
    def remove(self, force: bool = False) -> None: ...
450

451
class Network:
452
    id: str
453
    name: str
454
    driver: str
455
    scope: str
456
    
457
    def remove(self) -> None: ...
458

459
class Builder:
460
    name: str
461
    driver: str
462
    nodes: List[Dict[str, Any]]
463
    
464
    def remove(self) -> None: ...
465

466
class SystemInfo:
467
    id: str
468
    containers: int
469
    images: int
470
    server_version: str
471
    architecture: str
472
    operating_system: str
473
    kernel_version: str
474

475
class Version:
476
    client: Optional[Dict[str, Any]]
477
    server: Optional[Dict[str, Any]]
478

479
class DockerException(Exception):
480
    docker_command: List[str]
481
    return_code: int
482
    stdout: Optional[str]
483
    stderr: Optional[str]
484

485
class ClientNotFoundError(Exception):
486
    pass
487

488
class Config:
489
    id: str
490
    version: DockerObjectVersion
491
    created_at: datetime
492
    updated_at: datetime
493
    spec: ConfigSpec
494
    
495
    def remove(self) -> None: ...
496

497
class Context:
498
    name: str
499
    metadata: Dict[str, Any]
500
    endpoints: Dict[str, Any]
501
    tls_material: Dict[str, Any]
502
    storage: Dict[str, Any]
503
    
504
    def remove(self, force: bool = False) -> None: ...
505
    def use(self) -> None: ...
506

507
class DockerContextConfig:
508
    def __init__(
509
        self,
510
        host: str,
511
        ca_cert: Optional[str] = None,
512
        cert: Optional[str] = None,
513
        key: Optional[str] = None,
514
        skip_tls_verify: bool = False
515
    ): ...
516

517
class KubernetesContextConfig:
518
    def __init__(
519
        self,
520
        config_file: Optional[str] = None,
521
        context_override: Optional[str] = None,
522
        namespace_override: Optional[str] = None
523
    ): ...
524

525
class Node:
526
    id: str
527
    version: DockerObjectVersion
528
    created_at: datetime
529
    updated_at: datetime
530
    spec: NodeSpec
531
    description: NodeDescription
532
    status: NodeStatus
533
    manager_status: Optional[ManagerStatus]
534
    
535
    def update(self, **kwargs) -> None: ...
536
    def ps(self) -> List[Task]: ...
537

538
class Plugin:
539
    id: str
540
    name: str
541
    enabled: bool
542
    settings: PluginSettings
543
    plugin_reference: str
544
    config: PluginConfig
545
    
546
    def disable(self, force: bool = False) -> None: ...
547
    def enable(self, timeout: Optional[int] = None) -> None: ...
548
    def remove(self, force: bool = False) -> None: ...
549

550
class Pod:
551
    id: str
552
    name: str
553
    created: str
554
    state: str
555
    hostname: str
556
    labels: Dict[str, str]
557
    containers: List[Dict[str, Any]]
558
    
559
    def start(self) -> None: ...
560
    def stop(self, time: Optional[int] = None) -> None: ...
561
    def remove(self, force: bool = False, **kwargs) -> None: ...
562

563
class Secret:
564
    id: str
565
    created_at: datetime
566
    updated_at: datetime
567
    spec: SecretSpec
568
    
569
    def remove(self) -> None: ...
570

571
class Service:
572
    id: str
573
    version: DockerObjectVersion
574
    created_at: datetime
575
    updated_at: datetime
576
    spec: ServiceSpec
577
    endpoint: ServiceEndpoint
578
    
579
    def scale(self, new_scale: int, detach: bool = False) -> None: ...
580
    def update(self, **kwargs) -> None: ...
581
    def remove(self) -> None: ...
582
    def ps(self) -> List[Task]: ...
583

584
class Stack:
585
    name: str
586
    services: int
587
    orchestrator: str
588
    
589
    def remove(self) -> None: ...
590
    def ps(self) -> List[Task]: ...
591
    def services(self) -> List[Service]: ...
592

593
class Task:
594
    id: str
595
    version: DockerObjectVersion
596
    created_at: datetime
597
    updated_at: datetime
598
    name: str
599
    service_id: str
600
    node_id: str
601
    desired_state: str
602
    status: TaskStatus
603

604
class ManifestList:
605
    name: str
606
    schema_version: int
607
    media_type: str
608
    manifests: List[ManifestDescriptor]
609
    
610
    def remove(self) -> None: ...
611

612
class ContainerStats:
613
    container_id: str
614
    name: str
615
    cpu_percentage: float
616
    memory_usage: int
617
    memory_limit: int
618
    memory_percentage: float
619
    network_rx: int
620
    network_tx: int
621
    block_read: int
622
    block_write: int
623
    pids: int
624

625
class DockerObjectVersion:
626
    index: int
627

628
class DiskFreeResult:
629
    images_size: int
630
    containers_size: int
631
    volumes_size: int
632
    build_cache_size: int
633
```