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

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 – Complete CLI specification for the container build command
• 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:

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

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.

Step 3: Execute the Build

Run the container build command from your Dockerfile directory:

container build --tag my-app:latest .

According to 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:

container images | grep my-app

Push to any OCI-compatible registry using standard semantics:

container push my-app:latest

Advanced Build Techniques

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

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:

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:

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

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.

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