# How to Build Docker Images with Apple Container

> Learn to build OCI-compatible Docker images with Apple Container's native macOS CLI. Utilize BuildKit in a VM for custom resource limits & multi-arch builds.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-23

---

**Apple Container provides a native macOS `container` CLI that builds OCI-compatible images from standard Dockerfiles using BuildKit inside a lightweight VM, supporting custom resource limits and multi-architecture output.**

Apple Container is Apple's open-source, macOS-native container toolchain that eliminates the need for Docker Desktop while maintaining full OCI compatibility. When you build Docker images with Apple Container, the `container build` command executes BuildKit inside an isolated virtual machine, ensuring clean isolation while allowing precise control over CPU, memory, and architecture targeting. This guide covers the complete workflow from simple builds to advanced multi-architecture configurations using the actual source implementation found in the `apple/container` repository.

## Basic Build Workflow

Building a container image follows the familiar Dockerfile-based workflow. Any standard Dockerfile compatible with Docker works identically with Apple Container.

### Step 1: Prepare Your Dockerfile

Create a `Dockerfile` in your project directory. The repository includes a reference implementation in `examples/container-machine-vscode/Dockerfile` that demonstrates building a Swift-based environment:

```dockerfile

# examples/container-machine-vscode/Dockerfile

FROM swift:6.3.2-noble

RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    curl ca-certificates git sudo systemd openssh-server && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

EXPOSE 22
STOPSIGNAL SIGRTMIN+3
CMD ["/sbin/init"]

```

### Step 2: Execute the Build

Run the `container build` command from the directory containing your Dockerfile:

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

```

The `--tag` (`-t`) flag accepts multiple values for applying several tags simultaneously. Use `--file` (`-f`) to specify a non-default Dockerfile path. The full option list is documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md).

## Configuring Builder VM Resources

Unlike Docker Desktop, Apple Container explicitly manages a lightweight builder VM that executes your builds. By default, this VM receives 2 GiB of RAM and 2 CPU cores.

### Adjusting Resource Limits

For resource-intensive builds, start the builder with custom limits before building:

```bash
container builder start --cpus 8 --memory 32g

```

These settings persist until you stop or delete the builder. You can modify resources on-the-fly by stopping the current builder and restarting with new parameters:

```bash
container builder stop
container builder delete
container builder start --cpus 4 --memory 16g

```

Configuration details are specified in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md), which defines the builder VM resource allocation schema.

## Advanced Build Options

Apple Container supports sophisticated build scenarios including multi-architecture output and custom build arguments.

### Multi-Architecture Builds

Build for multiple processor architectures simultaneously using the `--arch` flag:

```bash
container build \
  --arch arm64 \
  --arch amd64 \
  --tag registry.example.com/myapp:latest \
  --file Dockerfile .

```

### Disabling Rosetta Translation

For native-only ARM builds without x86_64 translation, create a configuration file at `~/.config/container/config.toml`:

```bash
mkdir -p ~/.config/container && \
echo -e "[build]\nrosetta = false" > ~/.config/container/config.toml

```

This configuration prevents the builder from using Rosetta 2 for x86_64 emulation on Apple Silicon, as documented in the repository's configuration guides.

### Additional Build Arguments

Pass build-time variables and customize output formats:

```bash
container build \
  --build-arg VERSION=1.0.0 \
  --platform linux/arm64 \
  --output type=tar,dest=image.tar \
  --tag my-app:latest \
  .

```

## Pushing Images to Registries

After building, push images to any OCI-compatible registry using the `container push` command:

```bash
container push my-app:latest

```

This follows standard Docker semantics and supports registry authentication configured through standard Docker credential helpers.

## Summary

- Apple Container uses a dedicated builder VM running BuildKit to execute builds, providing isolation and resource control.
- The `container build` command accepts standard Dockerfile syntax and supports `--tag`, `--file`, `--build-arg`, and `--platform` flags.
- Resource limits default to 2 CPUs and 2 GiB RAM but can be customized via `container builder start --cpus` and `--memory`.
- Multi-architecture images are built by specifying multiple `--arch` values in a single command.
- Configuration files in `~/.config/container/config.toml` control advanced settings like Rosetta translation behavior.

## Frequently Asked Questions

### Can Apple Container build existing Dockerfiles without modification?

Yes. Apple Container maintains full compatibility with standard Dockerfile syntax. Any Dockerfile that works with Docker will work with Apple Container, as verified by the example in `examples/container-machine-vscode/Dockerfile`.

### How do I increase memory for large builds?

Start the builder VM with explicit resource flags before running your build: `container builder start --cpus 8 --memory 32g`. You must stop and delete the existing builder to apply new resource limits, as detailed in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).

### Does Apple Container support multi-architecture builds?

Yes. Use the `--arch` flag multiple times to specify target architectures (e.g., `--arch arm64 --arch amd64`). The builder produces a multi-manifest image supporting both architectures simultaneously.

### Where does Apple Container store builder configuration?

Builder configuration is stored in `~/.config/container/config.toml`, controlling VM resources, Rosetta translation settings, and other build-time parameters as defined in the [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md) specification.