# How to Build a Docker Image with Apple Container: A Complete Guide

> Learn to build OCI-compatible Docker images with Apple Container CLI. This guide covers Dockerfiles, BuildKit VM, resource limits, multi-architecture output, and registry pushes.

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

---

**Apple Container provides a native macOS `container` CLI that builds OCI-compatible images from standard Dockerfiles using an isolated BuildKit virtual machine, supporting resource limits, multi-architecture output, and direct registry pushes.**

Apple Container (available at `github.com/apple/container`) brings native container image building to macOS through a lightweight command-line interface. You can **build a Docker image with Apple Container** using the exact same Dockerfile syntax and workflow patterns familiar from Docker Desktop, while leveraging macOS-optimized virtualization for improved build isolation and resource control.

## Understanding the Build Architecture

Apple Container executes builds inside a lightweight virtual machine running BuildKit. This architecture provides process isolation from your host macOS system while enabling precise control over CPU and memory allocation for resource-intensive compilation tasks.

The build system references three key documentation files in the repository:
- [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) – Complete CLI specification for the `container build` command
- [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md) – Builder VM resource and configuration management
- `examples/container-machine-vscode/Dockerfile` – Sample Dockerfile demonstrating Swift-based builds

## Building Your First Image

### Step 1: Create a Dockerfile

Apple Container accepts standard Dockerfile syntax without modification. The repository includes a working example at `examples/container-machine-vscode/Dockerfile` that builds a Swift development 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: Configure Builder Resources (Optional)

By default, the builder VM allocates 2 CPU cores and 2 GiB RAM. For complex builds, start the builder with increased limits before executing your build:

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

```

These settings persist until you stop or delete the builder. Resource configuration details are documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).

### Step 3: Execute the Build

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

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

```

According to [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), the `container build` command supports:
- `--tag` (`-t`): Tag the image (repeatable for multiple tags)
- `--file` (`-f`): Specify an alternate Dockerfile path
- `--build-arg`: Pass build-time variables to the build
- `--output`: Export to tar archive or directory instead of local image store

### Step 4: Verify and Distribute

Confirm successful image creation:

```bash
container images | grep my-app

```

Push to any OCI-compatible registry using standard semantics:

```bash
container push my-app:latest

```

## Advanced Build Techniques

### 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 \
  .

```

### Disabling Rosetta Translation

For native-only ARM builds on Apple Silicon, disable x86_64 emulation by creating a configuration file at `~/.config/container/config.toml` as documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md):

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

```

This ensures pure native builds without binary translation overhead.

### Dynamic Resource Management

Change builder resources mid-session by recycling the VM:

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

```

## Summary

- **Apple Container** uses a BuildKit-powered VM to build Docker images from standard Dockerfiles with full OCI compatibility
- The `container build` command supports `--tag`, `--file`, `--build-arg`, and `--output` flags as specified in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)
- Builder VMs default to 2 CPUs and 2 GiB RAM, adjustable via `container builder start --cpus` and `--memory`
- Multi-architecture builds use `--arch` or `--platform` flags to generate cross-platform images from a single Dockerfile
- Images integrate with standard registry workflows through `container push` and local storage via `container images`

## Frequently Asked Questions

### Does Apple Container support standard Dockerfile syntax?

Yes. Apple Container parses standard Dockerfiles and Containerfiles without modification. The build process demonstrated in `examples/container-machine-vscode/Dockerfile` confirms that `FROM`, `RUN`, `EXPOSE`, and `CMD` instructions work identically to Docker implementations.

### How do I allocate more memory for complex builds?

Start the builder VM with explicit resource flags before building: `container builder start --cpus 8 --memory 32g`. These settings persist until you explicitly stop the builder with `container builder stop` or delete it with `container builder delete`, as documented in [`docs/container-system-config.md`](https://github.com/apple/container/blob/main/docs/container-system-config.md).

### Can I build for Intel (x86_64) from my Apple Silicon Mac?

Yes. Use `container build --arch amd64` or create multi-arch images with `container build --arch arm64 --arch amd64`. By default, Rosetta translation enables x86_64 builds on Apple Silicon, though you can disable this translation layer in `~/.config/container/config.toml` if you require native-only builds.

### Where are the built images stored?

Images are stored in the Apple Container local image store, accessible via `container images`. They follow OCI standards and can be exported using `container build --output` or pushed directly to registries using `container push`.