0
# Image Management
1

2
Image building, pulling, pushing, and management operations including legacy build and modern buildx support. Images serve as templates for creating containers and can be distributed through registries.
3

4
## Capabilities
5

6
### Image Retrieval and Distribution
7

8
Pull images from registries and push local images to remote repositories.
9

10
```python { .api }
11
def pull(
12
    image_name: str,
13
    *,
14
    platform: Optional[str] = None,
15
    all_tags: bool = False,
16
    quiet: bool = False
17
) -> Image:
18
    """
19
    Pull image from registry.
20
    
21
    Parameters:
22
    - image_name: Image repository name and tag
23
    - platform: Target platform (linux/amd64, linux/arm64, etc.)
24
    - all_tags: Pull all tagged images in repository
25
    - quiet: Suppress verbose output
26
    
27
    Returns:
28
    - Image object
29
    """
30

31
def push(
32
    image_name: str,
33
    *,
34
    all_tags: bool = False,
35
    quiet: bool = False
36
) -> str:
37
    """
38
    Push image to registry.
39
    
40
    Parameters:
41
    - image_name: Image repository name and tag
42
    - all_tags: Push all tagged images in repository
43
    - quiet: Suppress verbose output
44
    
45
    Returns:
46
    - Push operation output
47
    """
48
```
49

50
### Image Building
51

52
Build images from Dockerfiles using legacy build or modern buildx.
53

54
```python { .api }
55
def build(
56
    context_path: str,
57
    *,
58
    tags: Optional[List[str]] = None,
59
    dockerfile: Optional[str] = None,
60
    build_args: Optional[Dict[str, str]] = None,
61
    target: Optional[str] = None,
62
    no_cache: bool = False,
63
    pull: bool = False,
64
    rm: bool = True,
65
    force_rm: bool = False,
66
    labels: Optional[Dict[str, str]] = None,
67
    cache_from: Optional[List[str]] = None,
68
    platforms: Optional[List[str]] = None,
69
    push: bool = False,
70
    load: bool = True,
71
    progress: str = "auto"
72
) -> Image:
73
    """
74
    Build image from Dockerfile using buildx.
75
    
76
    Parameters:
77
    - context_path: Build context directory
78
    - tags: Image tags to apply
79
    - dockerfile: Dockerfile path (relative to context)
80
    - build_args: Build-time variables
81
    - target: Target build stage
82
    - no_cache: Don't use cache when building
83
    - pull: Always pull newer version of base image
84
    - rm: Remove intermediate containers
85
    - force_rm: Always remove intermediate containers
86
    - labels: Image labels
87
    - cache_from: Images to consider as cache sources
88
    - platforms: Target platforms for multi-platform builds
89
    - push: Push image after building
90
    - load: Load image to local Docker daemon
91
    - progress: Progress output type (auto, plain, tty)
92
    
93
    Returns:
94
    - Image object (if load=True)
95
    """
96

97
def legacy_build(
98
    context_path: str,
99
    *,
100
    tags: Optional[List[str]] = None,
101
    dockerfile: Optional[str] = None,
102
    build_args: Optional[Dict[str, str]] = None,
103
    target: Optional[str] = None,
104
    no_cache: bool = False,
105
    pull: bool = False,
106
    rm: bool = True,
107
    force_rm: bool = False,
108
    labels: Optional[Dict[str, str]] = None,
109
    cache_from: Optional[List[str]] = None
110
) -> Image:
111
    """
112
    Build image using legacy docker build.
113
    
114
    Parameters: Same as build() but without buildx-specific options
115
    
116
    Returns:
117
    - Image object
118
    """
119
```
120

121
### Image Listing and Inspection
122

123
List and inspect images with filtering and detailed information retrieval.
124

125
```python { .api }
126
def list(
127
    repository_name: Optional[str] = None,
128
    *,
129
    all: bool = False,
130
    filters: Optional[Dict[str, str]] = None,
131
    quiet: bool = False,
132
    no_trunc: bool = False,
133
    digests: bool = False
134
) -> List[Image]:
135
    """
136
    List images.
137
    
138
    Parameters:
139
    - repository_name: Filter by repository name
140
    - all: Show all images (including intermediate)
141
    - filters: Filters to apply (dangling, label, etc.)
142
    - quiet: Only show image IDs
143
    - no_trunc: Don't truncate output
144
    - digests: Show image digests
145
    
146
    Returns:
147
    - List of Image objects
148
    """
149

150
def inspect(image: str) -> Image:
151
    """
152
    Get detailed information about an image.
153
    
154
    Parameters:
155
    - image: Image name, ID, or digest
156
    
157
    Returns:
158
    - Image object with full details
159
    """
160

161
def exists(image: str) -> bool:
162
    """
163
    Check if image exists locally.
164
    
165
    Parameters:
166
    - image: Image name, ID, or digest
167
    
168
    Returns:
169
    - True if image exists, False otherwise
170
    """
171
```
172

173
### Image History and Analysis
174

175
View image layer history and analyze image composition.
176

177
```python { .api }
178
def history(
179
    image: str,
180
    *,
181
    human: bool = True,
182
    quiet: bool = False,
183
    no_trunc: bool = False
184
) -> List[Dict[str, Any]]:
185
    """
186
    Show image layer history.
187
    
188
    Parameters:
189
    - image: Image name, ID, or digest
190
    - human: Human readable sizes
191
    - quiet: Only show image IDs
192
    - no_trunc: Don't truncate output
193
    
194
    Returns:
195
    - List of layer information dictionaries
196
    """
197
```
198

199
### Image Manipulation
200

201
Tag, save, load, and import images.
202

203
```python { .api }
204
def tag(
205
    source_image: str,
206
    target_repository: str,
207
    target_tag: Optional[str] = None
208
) -> None:
209
    """
210
    Create tag for image.
211
    
212
    Parameters:
213
    - source_image: Source image name or ID
214
    - target_repository: Target repository name
215
    - target_tag: Target tag (defaults to 'latest')
216
    """
217

218
def save(
219
    images: Union[str, List[str]],
220
    output_path: str
221
) -> None:
222
    """
223
    Save images to tar archive.
224
    
225
    Parameters:
226
    - images: Image name(s) or ID(s)
227
    - output_path: Output tar file path
228
    """
229

230
def load(input_path: str, quiet: bool = False) -> List[str]:
231
    """
232
    Load images from tar archive.
233
    
234
    Parameters:
235
    - input_path: Input tar file path
236
    - quiet: Suppress load output
237
    
238
    Returns:
239
    - List of loaded image names
240
    """
241

242
def import_(
243
    source: str,
244
    repository: Optional[str] = None,
245
    tag: Optional[str] = None,
246
    message: Optional[str] = None,
247
    changes: Optional[List[str]] = None
248
) -> Image:
249
    """
250
    Import image from tarball or URL.
251
    
252
    Parameters:
253
    - source: Source tarball path or URL
254
    - repository: Repository name for imported image
255
    - tag: Tag for imported image
256
    - message: Commit message
257
    - changes: Dockerfile instructions to apply
258
    
259
    Returns:
260
    - Image object
261
    """
262
```
263

264
### Image Cleanup
265

266
Remove images and clean up unused images.
267

268
```python { .api }
269
def remove(
270
    images: Union[str, List[str]],
271
    *,
272
    force: bool = False,
273
    no_prune: bool = False
274
) -> None:
275
    """
276
    Remove images.
277
    
278
    Parameters:
279
    - images: Image name(s), ID(s), or digest(s)
280
    - force: Force removal of image
281
    - no_prune: Don't delete untagged parents
282
    """
283

284
def prune(
285
    *,
286
    all: bool = False,
287
    filters: Optional[Dict[str, str]] = None
288
) -> Dict[str, Any]:
289
    """
290
    Remove unused images.
291
    
292
    Parameters:
293
    - all: Remove all unused images, not just dangling ones
294
    - filters: Filters to apply
295
    
296
    Returns:
297
    - Information about removed images
298
    """
299
```
300

301
### File Operations
302

303
Copy files between images and host filesystem.
304

305
```python { .api }
306
def copy_from(
307
    image: str,
308
    source_path: str,
309
    destination_path: str
310
) -> None:
311
    """
312
    Copy files from image to host.
313
    
314
    Parameters:
315
    - image: Image name or ID
316
    - source_path: Source path in image
317
    - destination_path: Destination path on host
318
    """
319

320
def copy_to(
321
    source_path: str,
322
    image: str,
323
    destination_path: str
324
) -> None:
325
    """
326
    Copy files from host to image (creates new layer).
327
    
328
    Parameters:
329
    - source_path: Source path on host
330
    - image: Target image name or ID
331
    - destination_path: Destination path in image
332
    """
333
```
334

335
## Types
336

337
```python { .api }
338
class Image:
339
    id: str
340
    repo_tags: List[str]
341
    repo_digests: List[str]
342
    parent: str
343
    comment: str
344
    created: str
345
    container: str
346
    docker_version: str
347
    author: str
348
    config: Dict[str, Any]
349
    architecture: str
350
    os: str
351
    size: int
352
    virtual_size: int
353
    graph_driver: Dict[str, Any]
354
    root_fs: Dict[str, Any]
355
    metadata: Dict[str, Any]
356
    
357
    def remove(self, force: bool = False, no_prune: bool = False) -> None: ...
358
    def tag(self, repository: str, tag: Optional[str] = None) -> None: ...
359
    def save(self, output_path: str) -> None: ...
360
    def copy_from(self, source_path: str, destination_path: str) -> None: ...
361
    def copy_to(self, source_path: str, destination_path: str) -> None: ...
362
    def history(self, human: bool = True, quiet: bool = False, no_trunc: bool = False) -> List[Dict[str, Any]]: ...
363
    def exists(self) -> bool: ...
364
```