0
# Container Operations
1

2
Comprehensive container lifecycle management including creation, execution, monitoring, and cleanup operations. Containers represent running instances of Docker images with isolated processes, filesystems, and networking.
3

4
## Capabilities
5

6
### Container Creation and Running
7

8
Create and run containers from images with extensive configuration options for networking, volumes, environment variables, and resource constraints.
9

10
```python { .api }
11
def run(
12
    image: str,
13
    command: Optional[Sequence[str]] = (),
14
    *,
15
    add_hosts: Optional[List[Tuple[str, str]]] = None,
16
    blkio_weight: Optional[int] = None,
17
    cap_add: Optional[List[str]] = None,
18
    cap_drop: Optional[List[str]] = None,
19
    cgroup_parent: Optional[str] = None,
20
    cgroupns: Optional[str] = None,
21
    cidfile: Optional[str] = None,
22
    cpu_period: Optional[int] = None,
23
    cpu_quota: Optional[int] = None,
24
    cpu_shares: Optional[int] = None,
25
    cpus: Optional[float] = None,
26
    cpuset_cpus: Optional[List[int]] = None,
27
    cpuset_mems: Optional[List[int]] = None,
28
    detach: bool = False,
29
    devices: Optional[List[str]] = None,
30
    dns: Optional[List[str]] = None,
31
    dns_options: Optional[List[str]] = None,
32
    dns_search: Optional[List[str]] = None,
33
    domainname: Optional[str] = None,
34
    entrypoint: Optional[str] = None,
35
    envs: Optional[Dict[str, str]] = None,
36
    env_files: Optional[List[str]] = None,
37
    env_host: bool = False,
38
    expose: Optional[List[int]] = None,
39
    gpus: Optional[Union[int, str]] = None,
40
    groups_add: Optional[List[str]] = None,
41
    healthcheck: bool = True,
42
    health_cmd: Optional[str] = None,
43
    health_interval: Optional[Union[int, str]] = None,
44
    health_retries: Optional[int] = None,
45
    health_start_period: Optional[Union[int, str]] = None,
46
    health_timeout: Optional[Union[int, str]] = None,
47
    hostname: Optional[str] = None,
48
    init: bool = False,
49
    interactive: bool = False,
50
    ip: Optional[str] = None,
51
    ip6: Optional[str] = None,
52
    ipc: Optional[str] = None,
53
    isolation: Optional[str] = None,
54
    kernel_memory: Optional[Union[int, str]] = None,
55
    labels: Optional[Dict[str, str]] = None,
56
    label_files: Optional[List[str]] = None,
57
    link: Optional[List[str]] = None,
58
    link_local_ip: Optional[List[str]] = None,
59
    log_driver: Optional[str] = None,
60
    log_options: Optional[List[str]] = None,
61
    mac_address: Optional[str] = None,
62
    memory: Optional[Union[int, str]] = None,
63
    memory_reservation: Optional[Union[int, str]] = None,
64
    memory_swap: Optional[Union[int, str]] = None,
65
    memory_swappiness: Optional[int] = None,
66
    mounts: Optional[List[str]] = None,
67
    name: Optional[str] = None,
68
    networks: Optional[List[str]] = None,
69
    network_aliases: Optional[List[str]] = None,
70
    oom_kill: bool = True,
71
    oom_score_adj: Optional[int] = None,
72
    pid: Optional[str] = None,
73
    pids_limit: Optional[int] = None,
74
    platform: Optional[str] = None,
75
    pod: Optional[str] = None,
76
    preserve_fds: Optional[int] = None,
77
    privileged: bool = False,
78
    publish: Optional[List[str]] = None,
79
    publish_all: bool = False,
80
    pull: str = "missing",
81
    read_only: bool = False,
82
    restart: Optional[str] = None,
83
    remove: bool = False,
84
    runtime: Optional[str] = None,
85
    security_options: Optional[List[str]] = None,
86
    shm_size: Optional[Union[int, str]] = None,
87
    sig_proxy: bool = True,
88
    stop_signal: Optional[Union[int, str]] = None,
89
    stop_timeout: Optional[int] = None,
90
    storage_options: Optional[List[str]] = None,
91
    stream: bool = False,
92
    sysctl: Optional[Dict[str, str]] = None,
93
    systemd: Optional[Union[bool, str]] = None,
94
    tmpfs: Optional[List[str]] = None,
95
    tty: bool = False,
96
    tz: Optional[str] = None,
97
    ulimit: Optional[List[str]] = None,
98
    user: Optional[str] = None,
99
    userns: Optional[str] = None,
100
    uts: Optional[str] = None,
101
    volumes: Optional[List[str]] = None,
102
    volume_driver: Optional[str] = None,
103
    volumes_from: Optional[List[str]] = None,
104
    workdir: Optional[str] = None
105
) -> Union[str, Container]:
106
    """
107
    Run a container from an image with comprehensive configuration options.
108
    
109
    Parameters:
110
    - image: Docker image name or ID
111
    - command: Command to run in container
112
    - add_hosts: Host to IP mappings
113
    - blkio_weight: Block IO weight (10-1000)
114
    - cap_add: Linux capabilities to add
115
    - cap_drop: Linux capabilities to drop
116
    - cgroup_parent: Parent cgroup for container
117
    - cgroupns: Cgroup namespace mode
118
    - cidfile: Write container ID to file
119
    - cpu_period: CPU CFS period limit
120
    - cpu_quota: CPU CFS quota limit
121
    - cpu_shares: CPU shares (relative weight)
122
    - cpus: Number of CPUs
123
    - cpuset_cpus: CPUs to use
124
    - cpuset_mems: Memory nodes to use
125
    - detach: Run container in background
126
    - devices: Device mappings
127
    - dns: DNS servers
128
    - dns_options: DNS options
129
    - dns_search: DNS search domains
130
    - domainname: Container NIS domain name
131
    - entrypoint: Override image entrypoint
132
    - envs: Environment variables as dict
133
    - env_files: Environment files to load
134
    - env_host: Use host environment variables
135
    - expose: Expose ports without publishing
136
    - gpus: GPU devices to use
137
    - groups_add: Additional groups for user
138
    - healthcheck: Enable/disable healthcheck
139
    - health_cmd: Health check command
140
    - health_interval: Health check interval
141
    - health_retries: Health check retries
142
    - health_start_period: Health check start period
143
    - health_timeout: Health check timeout
144
    - hostname: Container hostname
145
    - init: Run init inside container
146
    - interactive: Keep STDIN open
147
    - ip: IPv4 address
148
    - ip6: IPv6 address
149
    - ipc: IPC mode
150
    - isolation: Container isolation technology
151
    - kernel_memory: Kernel memory limit
152
    - labels: Container labels
153
    - label_files: Label files to read
154
    - link: Link to containers (deprecated)
155
    - link_local_ip: Container IPv4/IPv6 link-local addresses
156
    - log_driver: Logging driver
157
    - log_options: Log driver options
158
    - mac_address: Container MAC address
159
    - memory: Memory limit
160
    - memory_reservation: Memory soft limit
161
    - memory_swap: Swap limit
162
    - memory_swappiness: Tune container memory swappiness
163
    - mounts: Filesystem mounts
164
    - name: Container name
165
    - networks: Networks to connect to
166
    - network_aliases: Network-scoped aliases
167
    - oom_kill: Enable OOM killer
168
    - oom_score_adj: OOM score adjustment
169
    - pid: PID namespace mode
170
    - pids_limit: PIDs limit
171
    - platform: Target platform
172
    - pod: Pod to join (Podman)
173
    - preserve_fds: Preserve additional file descriptors
174
    - privileged: Run with extended privileges
175
    - publish: Port mappings
176
    - publish_all: Publish all exposed ports
177
    - pull: Pull image policy (always, missing, never)
178
    - read_only: Mount root filesystem as read-only
179
    - restart: Restart policy
180
    - remove: Remove container when it exits
181
    - runtime: Runtime to use
182
    - security_options: Security options
183
    - shm_size: Size of /dev/shm
184
    - sig_proxy: Proxy received signals to process
185
    - stop_signal: Signal to stop container
186
    - stop_timeout: Timeout to stop container
187
    - storage_options: Storage driver options
188
    - stream: Stream container output
189
    - sysctl: Sysctl options
190
    - systemd: Enable systemd mode
191
    - tmpfs: Tmpfs mounts
192
    - tty: Allocate pseudo-TTY
193
    - tz: Timezone
194
    - ulimit: Ulimit options
195
    - user: User to run as
196
    - userns: User namespace mode
197
    - uts: UTS namespace mode
198
    - volumes: Volume mounts
199
    - volume_driver: Volume driver
200
    - volumes_from: Mount volumes from containers
201
    - workdir: Working directory
202
    
203
    Returns:
204
    - Container object if detach=True, output string otherwise
205
    """
206

207
def create(
208
    image: str,
209
    command: Optional[List[str]] = None,
210
    **kwargs
211
) -> Container:
212
    """
213
    Create a container without starting it.
214
    
215
    Parameters:
216
    - image: Docker image name or ID
217
    - command: Command to run in container
218
    - **kwargs: Same options as run()
219
    
220
    Returns:
221
    - Container object
222
    """
223
```
224

225
### Container Listing and Inspection
226

227
List and inspect containers with filtering and detailed information retrieval.
228

229
```python { .api }
230
def ps(
231
    all: bool = False,
232
    filters: Optional[Dict[str, str]] = None,
233
    size: bool = False,
234
    latest: bool = False,
235
    quiet: bool = False
236
) -> List[Container]:
237
    """
238
    List containers.
239
    
240
    Parameters:
241
    - all: Show all containers (default shows just running)
242
    - filters: Filters to apply (name, status, etc.)
243
    - size: Include container sizes
244
    - latest: Show only latest created container
245
    - quiet: Only display container IDs
246
    
247
    Returns:
248
    - List of Container objects
249
    """
250

251
def inspect(container: str) -> Container:
252
    """
253
    Get detailed information about a container.
254
    
255
    Parameters:
256
    - container: Container name or ID
257
    
258
    Returns:
259
    - Container object with full details
260
    """
261
```
262

263
### Container Lifecycle Control
264

265
Start, stop, restart, and manage container execution states.
266

267
```python { .api }
268
def start(containers: Union[str, List[str]]) -> None:
269
    """
270
    Start one or more containers.
271
    
272
    Parameters:
273
    - containers: Container name(s) or ID(s)
274
    """
275

276
def stop(
277
    containers: Union[str, List[str]],
278
    timeout: Optional[int] = None
279
) -> None:
280
    """
281
    Stop running containers.
282
    
283
    Parameters:
284
    - containers: Container name(s) or ID(s)
285
    - timeout: Seconds to wait before force killing
286
    """
287

288
def restart(
289
    containers: Union[str, List[str]],
290
    timeout: Optional[int] = None
291
) -> None:
292
    """
293
    Restart containers.
294
    
295
    Parameters:
296
    - containers: Container name(s) or ID(s)
297
    - timeout: Seconds to wait before force killing
298
    """
299

300
def kill(
301
    containers: Union[str, List[str]],
302
    signal: str = "SIGKILL"
303
) -> None:
304
    """
305
    Kill running containers.
306
    
307
    Parameters:
308
    - containers: Container name(s) or ID(s)
309
    - signal: Signal to send (SIGKILL, SIGTERM, etc.)
310
    """
311

312
def pause(containers: Union[str, List[str]]) -> None:
313
    """
314
    Pause containers (suspend all processes).
315
    
316
    Parameters:
317
    - containers: Container name(s) or ID(s)
318
    """
319

320
def unpause(containers: Union[str, List[str]]) -> None:
321
    """
322
    Unpause containers.
323
    
324
    Parameters:
325
    - containers: Container name(s) or ID(s)
326
    """
327
```
328

329
### Container Execution and Interaction
330

331
Execute commands in running containers and interact with container processes.
332

333
```python { .api }
334
def execute(
335
    container: str,
336
    command: List[str],
337
    *,
338
    detach: bool = False,
339
    interactive: bool = False,
340
    tty: bool = False,
341
    user: Optional[str] = None,
342
    workdir: Optional[str] = None,
343
    envs: Optional[Dict[str, str]] = None,
344
    privileged: bool = False
345
) -> str:
346
    """
347
    Execute command in running container.
348
    
349
    Parameters:
350
    - container: Container name or ID
351
    - command: Command to execute
352
    - detach: Run command in background
353
    - interactive: Keep STDIN open
354
    - tty: Allocate pseudo-TTY
355
    - user: User to run as
356
    - workdir: Working directory
357
    - envs: Environment variables
358
    - privileged: Run with extended privileges
359
    
360
    Returns:
361
    - Command output (if not detached)
362
    """
363

364
def attach(container: str, detach_keys: Optional[str] = None) -> None:
365
    """
366
    Attach to running container.
367
    
368
    Parameters:
369
    - container: Container name or ID
370
    - detach_keys: Key sequence for detaching
371
    """
372
```
373

374
### Container Logs and Monitoring
375

376
Retrieve container logs and monitor container statistics.
377

378
```python { .api }
379
def logs(
380
    container: str,
381
    *,
382
    follow: bool = False,
383
    tail: Optional[int] = None,
384
    since: Optional[str] = None,
385
    until: Optional[str] = None,
386
    timestamps: bool = False,
387
    details: bool = False
388
) -> str:
389
    """
390
    Get container logs.
391
    
392
    Parameters:
393
    - container: Container name or ID
394
    - follow: Follow log output
395
    - tail: Number of lines from end of logs
396
    - since: Show logs since timestamp
397
    - until: Show logs until timestamp
398
    - timestamps: Show timestamps
399
    - details: Show extra log details
400
    
401
    Returns:
402
    - Log output string
403
    """
404

405
def stats(
406
    containers: Optional[List[str]] = None,
407
    all: bool = False,
408
    no_stream: bool = True
409
) -> Union[List[ContainerStats], Iterator[List[ContainerStats]]]:
410
    """
411
    Get container resource usage statistics.
412
    
413
    Parameters:
414
    - containers: Specific containers to monitor
415
    - all: Include stopped containers
416
    - no_stream: Return single result instead of stream
417
    
418
    Returns:
419
    - Container statistics (list or iterator)
420
    """
421

422
def top(container: str, ps_options: Optional[str] = None) -> List[Dict[str, str]]:
423
    """
424
    Display running processes in container.
425
    
426
    Parameters:
427
    - container: Container name or ID
428
    - ps_options: ps command options
429
    
430
    Returns:
431
    - List of process information dictionaries
432
    """
433
```
434

435
### Container File Operations
436

437
Copy files between containers and host filesystem.
438

439
```python { .api }
440
def copy(
441
    source: str,
442
    destination: str,
443
    *,
444
    archive: bool = False,
445
    follow_link: bool = False
446
) -> None:
447
    """
448
    Copy files/folders between container and host.
449
    
450
    Parameters:
451
    - source: Source path (container:path or host path)
452
    - destination: Destination path (container:path or host path)
453
    - archive: Preserve tar archive format
454
    - follow_link: Follow symbolic links in source
455
    """
456
```
457

458
### Container Management
459

460
Rename, update, and remove containers.
461

462
```python { .api }
463
def rename(container: str, new_name: str) -> None:
464
    """
465
    Rename container.
466
    
467
    Parameters:
468
    - container: Current container name or ID
469
    - new_name: New container name
470
    """
471

472
def update(
473
    containers: Union[str, List[str]],
474
    *,
475
    cpus: Optional[float] = None,
476
    memory: Optional[str] = None,
477
    restart: Optional[str] = None,
478
    **kwargs
479
) -> None:
480
    """
481
    Update container configuration.
482
    
483
    Parameters:
484
    - containers: Container name(s) or ID(s)
485
    - cpus: CPU limit
486
    - memory: Memory limit
487
    - restart: Restart policy
488
    """
489

490
def remove(
491
    containers: Union[str, List[str]],
492
    *,
493
    force: bool = False,
494
    volumes: bool = False,
495
    links: bool = False
496
) -> None:
497
    """
498
    Remove containers.
499
    
500
    Parameters:
501
    - containers: Container name(s) or ID(s)
502
    - force: Force removal of running containers
503
    - volumes: Remove associated volumes
504
    - links: Remove network links
505
    """
506

507
def prune(filters: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
508
    """
509
    Remove stopped containers.
510
    
511
    Parameters:
512
    - filters: Filters to apply
513
    
514
    Returns:
515
    - Information about removed containers
516
    """
517
```
518

519
### Container State Operations
520

521
Wait for containers and monitor state changes.
522

523
```python { .api }
524
def wait(
525
    containers: Union[str, List[str]],
526
    condition: str = "not-running"
527
) -> List[Dict[str, Any]]:
528
    """
529
    Wait for containers to reach specified condition.
530
    
531
    Parameters:
532
    - containers: Container name(s) or ID(s)
533
    - condition: Condition to wait for (not-running, next-exit, removed)
534
    
535
    Returns:
536
    - List of container exit information
537
    """
538

539
def diff(container: str) -> List[Dict[str, str]]:
540
    """
541
    Show changes to container filesystem.
542
    
543
    Parameters:
544
    - container: Container name or ID
545
    
546
    Returns:
547
    - List of filesystem changes
548
    """
549
```
550

551
## Types
552

553
```python { .api }
554
class Container:
555
    id: str
556
    name: str
557
    image: str
558
    command: str
559
    created: str
560
    state: str
561
    status: str
562
    ports: Dict[str, Any]
563
    labels: Dict[str, str]
564
    mounts: List[Dict[str, Any]]
565
    network_settings: Dict[str, Any]
566
    
567
    def remove(self, force: bool = False, volumes: bool = False) -> None: ...
568
    def start(self) -> None: ...
569
    def stop(self, timeout: Optional[int] = None) -> None: ...
570
    def restart(self, timeout: Optional[int] = None) -> None: ...
571
    def kill(self, signal: str = "SIGKILL") -> None: ...
572
    def pause(self) -> None: ...
573
    def unpause(self) -> None: ...
574
    def logs(self, follow: bool = False, tail: Optional[int] = None) -> str: ...
575
    def execute(self, command: List[str], **kwargs) -> str: ...
576
    def rename(self, new_name: str) -> None: ...
577
    def update(self, **kwargs) -> None: ...
578
    def copy_from(self, source_path: str, destination_path: str) -> None: ...
579
    def copy_to(self, source_path: str, destination_path: str) -> None: ...
580
    def export(self, output_path: str) -> None: ...
581
    def commit(self, repository: Optional[str] = None, tag: Optional[str] = None, **kwargs) -> Image: ...
582
    def diff(self) -> List[Dict[str, str]]: ...
583
    def stats(self, no_stream: bool = True) -> ContainerStats: ...
584
    def top(self, ps_options: Optional[str] = None) -> List[Dict[str, str]]: ...
585
    def wait(self, condition: str = "not-running") -> Dict[str, Any]: ...
586
    def attach(self, detach_keys: Optional[str] = None) -> None: ...
587

588
class ContainerStats:
589
    container_id: str
590
    name: str
591
    cpu_percentage: float
592
    memory_usage: str
593
    memory_percentage: float
594
    network_io: str
595
    block_io: str
596
    pids: int
597
```