0
# Build Operations
1

2
Advanced build operations using Docker Buildx for multi-platform builds and BuildKit features. Buildx extends Docker's native build capabilities with enhanced functionality for complex build scenarios.
3

4
## Capabilities
5

6
### Builder Management
7

8
Create and manage build instances with different drivers and configurations.
9

10
```python { .api }
11
def create(
12
    name: str,
13
    *,
14
    driver: Optional[str] = None,
15
    driver_options: Optional[Dict[str, str]] = None,
16
    platforms: Optional[List[str]] = None,
17
    config_file: Optional[str] = None,
18
    use: bool = False,
19
    append: bool = False,
20
    leave: bool = False
21
) -> Builder:
22
    """
23
    Create a new builder instance.
24
    
25
    Parameters:
26
    - name: Builder name
27
    - driver: Builder driver (docker-container, kubernetes, remote)
28
    - driver_options: Driver-specific options
29
    - platforms: Target platforms
30
    - config_file: BuildKit configuration file
31
    - use: Set as current builder
32
    - append: Append node to existing builder
33
    - leave: Remove current node before adding
34
    
35
    Returns:
36
    - Builder object
37
    """
38

39
def list() -> List[Builder]:
40
    """
41
    List available builder instances.
42
    
43
    Returns:
44
    - List of Builder objects
45
    """
46

47
def inspect(name: Optional[str] = None) -> Builder:
48
    """
49
    Get detailed information about a builder.
50
    
51
    Parameters:
52
    - name: Builder name (current builder if not specified)
53
    
54
    Returns:
55
    - Builder object with full details
56
    """
57

58
def use(name: str) -> None:
59
    """
60
    Set current builder instance.
61
    
62
    Parameters:
63
    - name: Builder name to use
64
    """
65

66
def remove(builders: Union[str, List[str]]) -> None:
67
    """
68
    Remove builder instances.
69
    
70
    Parameters:
71
    - builders: Builder name(s) to remove
72
    """
73

74
def stop(builders: Union[str, List[str]]) -> None:
75
    """
76
    Stop builder instances.
77
    
78
    Parameters:
79
    - builders: Builder name(s) to stop
80
    """
81
```
82

83
### Advanced Building
84

85
Build images with multi-platform support and advanced BuildKit features.
86

87
```python { .api }
88
def build(
89
    context_path: str,
90
    *,
91
    tags: Optional[List[str]] = None,
92
    builder: Optional[str] = None,
93
    build_args: Optional[Dict[str, str]] = None,
94
    cache_from: Optional[List[str]] = None,
95
    cache_to: Optional[List[str]] = None,
96
    file: Optional[str] = None,
97
    labels: Optional[Dict[str, str]] = None,
98
    load: bool = False,
99
    platforms: Optional[List[str]] = None,
100
    progress: str = "auto",
101
    pull: bool = False,
102
    push: bool = False,
103
    secrets: Optional[List[str]] = None,
104
    ssh: Optional[List[str]] = None,
105
    target: Optional[str] = None,
106
    ulimit: Optional[List[str]] = None,
107
    outputs: Optional[List[str]] = None,
108
    no_cache: bool = False,
109
    no_cache_filter: Optional[List[str]] = None,
110
    allow: Optional[List[str]] = None,
111
    attests: Optional[List[str]] = None,
112
    build_contexts: Optional[Dict[str, str]] = None,
113
    network: Optional[str] = None,
114
    quiet: bool = False,
115
    shm_size: Optional[str] = None
116
) -> Optional[Image]:
117
    """
118
    Build image using buildx.
119
    
120
    Parameters:
121
    - context_path: Build context directory
122
    - tags: Image tags to apply
123
    - builder: Builder instance to use
124
    - build_args: Build-time variables
125
    - cache_from: Cache import locations
126
    - cache_to: Cache export locations
127
    - file: Dockerfile path
128
    - labels: Image labels
129
    - load: Load image to docker daemon
130
    - platforms: Target platforms (linux/amd64, linux/arm64, etc.)
131
    - progress: Progress output type (auto, plain, tty)
132
    - pull: Always pull base images
133
    - push: Push image after building
134
    - secrets: Secrets to expose to build
135
    - ssh: SSH agent sockets
136
    - target: Target build stage
137
    - ulimit: Ulimit settings
138
    - outputs: Output destinations and formats
139
    - no_cache: Don't use cache
140
    - no_cache_filter: Ignore cache for specified stages
141
    - allow: Allow extra privileged entitlements
142
    - attests: Attestation options
143
    - build_contexts: Additional build contexts
144
    - network: Network mode during build
145
    - quiet: Suppress build output
146
    - shm_size: Size of /dev/shm
147
    
148
    Returns:
149
    - Image object (if load=True), None otherwise
150
    """
151
```
152

153
### Build Configuration and Recipes
154

155
Use bake files for complex multi-target builds.
156

157
```python { .api }
158
def bake(
159
    targets: Optional[List[str]] = None,
160
    *,
161
    file: Optional[List[str]] = None,
162
    load: bool = False,
163
    print_: bool = False,
164
    progress: str = "auto",
165
    pull: bool = False,
166
    push: bool = False,
167
    set_: Optional[List[str]] = None,
168
    builder: Optional[str] = None,
169
    no_cache: bool = False,
170
    call: Optional[str] = None
171
) -> None:
172
    """
173
    Build from bake file.
174
    
175
    Parameters:
176
    - targets: Build targets to execute
177
    - file: Bake file paths
178
    - load: Load images to docker daemon
179
    - print_: Print bake file in JSON format
180
    - progress: Progress output type
181
    - pull: Always pull base images
182
    - push: Push images after building
183
    - set_: Override build arguments
184
    - builder: Builder instance to use
185
    - no_cache: Don't use cache
186
    - call: Call build method (build, check, outline, targets)
187
    """
188
```
189

190
### Build Utilities
191

192
Manage build cache and inspect build history.
193

194
```python { .api }
195
def disk_usage() -> Dict[str, Any]:
196
    """
197
    Show buildx disk usage.
198
    
199
    Returns:
200
    - Disk usage information including build cache
201
    """
202

203
def prune(
204
    *,
205
    all: bool = False,
206
    filters: Optional[Dict[str, str]] = None,
207
    force: bool = False,
208
    keep_storage: Optional[str] = None
209
) -> Dict[str, Any]:
210
    """
211
    Remove build cache.
212
    
213
    Parameters:
214
    - all: Remove all cache, not just dangling
215
    - filters: Filters to apply
216
    - force: Don't prompt for confirmation
217
    - keep_storage: Amount of cache to keep
218
    
219
    Returns:
220
    - Information about removed cache
221
    """
222

223
def version() -> Dict[str, str]:
224
    """
225
    Get buildx version information.
226
    
227
    Returns:
228
    - Version information dictionary
229
    """
230

231
def is_installed() -> bool:
232
    """
233
    Check if buildx is available.
234
    
235
    Returns:
236
    - True if buildx is installed and available
237
    """
238
```
239

240
### Image Tools
241

242
Advanced image manipulation and multi-platform operations.
243

244
```python { .api }
245
class ImagetoolsCLI:
246
    def create(
247
        self,
248
        tags: List[str],
249
        *,
250
        sources: Optional[List[str]] = None,
251
        dry_run: bool = False,
252
        append: bool = False,
253
        progress: str = "auto"
254
    ) -> None:
255
        """
256
        Create multi-platform manifest.
257
        
258
        Parameters:
259
        - tags: Target image tags
260
        - sources: Source images to combine
261
        - dry_run: Show what would be created
262
        - append: Append to existing manifest
263
        - progress: Progress output type
264
        """
265
    
266
    def inspect(
267
        self,
268
        image: str,
269
        *,
270
        raw: bool = False,
271
        format: Optional[str] = None
272
    ) -> Dict[str, Any]:
273
        """
274
        Inspect multi-platform image.
275
        
276
        Parameters:
277
        - image: Image name or reference
278
        - raw: Show original manifest
279
        - format: Output format (json, template)
280
        
281
        Returns:
282
        - Image inspection information
283
        """
284
```
285

286
## Usage Examples
287

288
### Multi-Platform Building
289

290
```python
291
from python_on_whales import docker
292

293
# Create a builder for multi-platform builds
294
builder = docker.buildx.create(
295
    "multiplatform-builder",
296
    driver="docker-container",
297
    platforms=["linux/amd64", "linux/arm64"]
298
)
299
docker.buildx.use("multiplatform-builder")
300

301
# Build for multiple platforms
302
docker.buildx.build(
303
    ".",
304
    tags=["myapp:latest"],
305
    platforms=["linux/amd64", "linux/arm64"],
306
    push=True,
307
    cache_from=["type=registry,ref=myapp:cache"],
308
    cache_to=["type=registry,ref=myapp:cache,mode=max"]
309
)
310
```
311

312
### Advanced Build Features
313

314
```python
315
# Build with secrets and SSH forwarding
316
docker.buildx.build(
317
    ".",
318
    tags=["myapp:secure"],
319
    secrets=["id=mysecret,src=/path/to/secret"],
320
    ssh=["default=/path/to/ssh/key"],
321
    build_args={"BUILD_ENV": "production"},
322
    target="production"
323
)
324

325
# Build with custom outputs
326
docker.buildx.build(
327
    ".",
328
    tags=["myapp:local"],
329
    outputs=["type=local,dest=./output"],
330
    platforms=["linux/amd64"]
331
)
332

333
# Build using bake file
334
docker.buildx.bake(
335
    targets=["web", "api"],
336
    file=["docker-bake.json"],
337
    push=True,
338
    set_=["web.args.VERSION=v1.2.3"]
339
)
340
```
341

342
### Cache Management
343

344
```python
345
# Check disk usage
346
usage = docker.buildx.disk_usage()
347
print(f"Total cache size: {usage['Total']}")
348

349
# Clean up build cache
350
prune_result = docker.buildx.prune(
351
    all=True,
352
    keep_storage="10GB"
353
)
354
print(f"Freed: {prune_result['SpaceReclaimed']}")
355
```
356

357
## Types
358

359
```python { .api }
360
class Builder:
361
    name: str
362
    driver: str
363
    last_activity: Optional[str]
364
    dynamic: bool
365
    nodes: List[Dict[str, Any]]
366
    
367
    def remove(self) -> None: ...
368
    def use(self) -> None: ...
369
    def stop(self) -> None: ...
370

371
class BuilderNode:
372
    name: str
373
    endpoint: str
374
    driver_options: Dict[str, str]
375
    status: str
376
    flags: List[str]
377
    platforms: List[str]
378

379
class DiskUsageResult:
380
    build_cache: List[Dict[str, Any]]
381
    total_size: int
382
    reclaimable_size: int
383
```