# Container Build Options in Apple Container: Complete Command Reference

> Explore over 25 container build options in Apple Container. Customize architecture, resources, build args, output, and secrets with our comprehensive command reference.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: api-reference
- Published: 2026-07-11

---

**The `container build` command supports 25+ options including architecture selection (`--arch`), resource limits (`--cpus`, `--memory`), build-time variables (`--build-arg`), output formats (`--output`), and secure secrets management (`--secret`).**

The Apple Container project provides a native container builder that wraps Apple's BuildKit implementation. When you invoke the `container build` sub-command, the `BuildCommand` class parses these build options to configure the runtime environment, resource allocation, and export behavior. Understanding these container build options allows you to optimize build performance, target specific platforms, and manage sensitive data securely.

## Target Platform Selection

Building for specific hardware architectures and operating systems requires precise platform targeting.

### Architecture and OS Specification

The `--arch` (`-a`) flag adds a specific architecture type such as `arm64` or `x86_64` to the build. For broader platform control, the `--os` flag specifies the target operating system (e.g., `linux`). When you need complete platform specification, the `--platform` option takes precedence, accepting a string in the format `os/arch[/variant]` that overrides both `--os` and `--arch` individually.

These values are passed directly to BuildKit's platform selection logic in [`Sources/ContainerCommands/BuildCommand.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/BuildCommand.swift), ensuring the resulting image matches your target environment.

## Resource Allocation and Environment

The builder runs inside a containerized environment that consumes host resources. You can fine-tune these allocations to balance build speed against system load.

### CPU and Memory Limits

Use `--cpus` (`-c`) to allocate CPU cores to the builder container (default: `2`). The `--memory` (`-m`) flag controls RAM allocation, defaulting to `2048MB` and accepting size suffixes like `K`, `M`, `G`, `T`, or `P` for larger values. These limits are enforced by `BuilderStart.start` in [`Sources/ContainerCommands/Builder/BuilderStart.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Builder/BuilderStart.swift) when launching the builder shim.

### DNS Configuration

For custom network resolution within the builder, four related options control DNS behavior:

- `--dns <ip>` – Sets the nameserver IP address in the builder's [`/etc/resolv.conf`](https://github.com/apple/container/blob/main//etc/resolv.conf)
- `--dns-search <domain>` – Adds search domains for DNS resolution
- `--dns-domain <domain>` – Specifies the default DNS domain
- `--dns-option <option>` – Appends extra DNS options such as `ndots:5`

These settings propagate to the builder container's network configuration, ensuring external resources resolve correctly during the build process.

## Build Execution Control

Control how the builder retrieves source images and which stages of multi-stage Dockerfiles execute.

### Caching and Image Pulling

The `--no-cache` flag disables BuildKit's cache layer, forcing all build steps to rerun from scratch. This is useful for verifying that your build process remains reproducible or when you suspect stale cache issues. To ensure you have the latest base image dependencies, use `--pull` to trigger a fresh pull of base images before building begins.

### Multi-Stage Target Selection

When working with multi-stage Dockerfiles, the `--target` flag limits the build to a specific stage (e.g., `--target production`). This capability reduces build time and image size when you only need intermediate artifacts or specific build environments.

## Input and Output Configuration

Manage how build context enters the system and how finished images are exported.

### Build Arguments and Labels

Pass variables into your Dockerfile using `--build-arg <key=val>`, which maps to `ARG` statements in your Dockerfile. These arguments are collected into `builder.buildArgs` and forwarded to BuildKit. Similarly, `--label` (`-l`) attaches metadata to the resulting image by translating key-value pairs into BuildKit export metadata.

### Secrets Management

The `--secret` option provides secure build-time data without baking it into image layers. Acceptable formats include `id=<key>,env=<ENV_VAR>` or `id=<key>,src=<local/path>`. In [`Sources/ContainerCommands/BuildCommand.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/BuildCommand.swift), these secrets are mapped to a dictionary and written to temporary files for BuildKit consumption, ensuring sensitive data never appears in the final image history.

### Output Formats

The `--output` (`-o`) flag controls how the build artifact is exported, supporting three types:
- `type=oci` (default) – Exports as an OCI-compliant image
- `type=tar` – Creates a tarball archive
- `type=local` – Extracts to a local directory

These options are parsed into `Builder.BuildExport` objects that determine the final storage format of your built image.

## Image Tagging and Metadata

### Image Naming

The `--tag` (`-t`) flag assigns names and references to your built image. You can repeat this flag multiple times to apply multiple tags to a single build. Each tag is parsed using `Reference.parse` and added to the `imageNames` collection for the build session.

## Progress and Debugging

Monitor build status or suppress output for automation pipelines.

### Progress Display

The `--progress` flag accepts `auto`, `plain`, or `tty` values (default: `auto`). This setting determines whether a `Terminal` attaches to the build process for interactive progress bars. For CI/CD pipelines, use `--quiet` (`-q`) to disable `ProgressBar` updates entirely and suppress build output.

### Builder Communication

The `--vsock-port` flag configures the VSOCK port used to communicate with the builder shim (default: `8088`). This low-level setting, defined in [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/ContainerSystemConfig.swift), controls how the client dials the builder via `client.dial(id:"buildkit", port:vsockPort)`.

## Practical Examples

Build a simple image with a custom tag:

```bash
container build -t my-app:latest .

```

Build a specific production stage with extra resources and disabled caching:

```bash
container build --target production -c 4 -m 4G --no-cache -t prod-app .

```

Export as a tarball while injecting a secret from an environment variable:

```bash
container build --secret apikey,env=API_KEY -o type=tar,dest=app.tar -t my-app .

```

Build for a specific architecture with custom DNS:

```bash
container build --arch arm64 --dns 8.8.8.8 --build-arg VERSION=1.0 -t arm-app .

```

## Summary

- **Container build options** in the Apple Container project provide granular control over the BuildKit implementation, from platform targeting to resource management.
- **Architecture selection** uses `--arch`, `--os`, and `--platform`, with the latter taking precedence when multiple flags are present.
- **Resource limits** specified via `--cpus` and `--memory` constrain the builder container's runtime environment through `BuilderStart.start`.
- **Secure builds** leverage `--secret` to inject sensitive data without exposing it in image layers, while `--no-cache` ensures reproducible builds.
- **Output flexibility** through the `--output` flag supports OCI images, tarballs, or local directory extraction via `Builder.BuildExport` logic.

## Frequently Asked Questions

### What is the default resource allocation for the container builder?

By default, the builder container receives **2 CPUs** and **2048MB of memory** when started via `BuilderStart.start`. You can override these defaults using the `--cpus` (`-c`) and `--memory` (`-m`) flags, with memory values supporting standard suffixes like `G` for gigabytes or `M` for megabytes.

### How do I disable caching during a build?

Pass the `--no-cache` flag to force BuildKit to rerun every build step from scratch, ignoring any previously cached layers. This option sets the `noCache` flag on the BuildKit request and is useful for verifying build reproducibility or troubleshooting cache-related issues.

### Can I specify multiple architectures in a single build command?

While you can add multiple `--arch` flags to specify target architectures, the platform resolution ultimately depends on BuildKit's capabilities and the `--platform` specification. The `--platform` flag accepts a complete platform string like `linux/arm64` and takes precedence over individual `--os` and `--arch` flags when constructing the target platform.

### Where are build secrets stored during the build process?

According to the implementation in [`Sources/ContainerCommands/BuildCommand.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/BuildCommand.swift), secrets provided via `--secret` are mapped to a dictionary and written to **temporary files** that BuildKit can access during the build. These files exist only for the duration of the build process and are not included in the final image layers, ensuring sensitive data remains ephemeral and secure.