How to Build Docker Images with Apple Container

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:

# 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:

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.

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:

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:

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

Configuration details are specified in 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:

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:

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:

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:

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.

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 specification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}