Migrating from Docker Desktop to container on Apple Silicon Macs: A Complete Guide

Uninstall Docker Desktop, install the signed Apple Container package, and replace docker commands with container to run Linux containers natively on M-series chips with near-native performance.

Apple's open-source container tool provides a lightweight, native alternative to Docker Desktop for developers running Apple Silicon Macs. This migration guide walks you through transitioning your container workflows from Docker Desktop to the container CLI, leveraging the Swift-based implementation in the apple/container repository for improved performance on M-series chips.

Why Migrate to Apple Container?

Native Apple Silicon support distinguishes container from Docker Desktop's emulation layers. The tool runs Linux containers inside lightweight virtual machines built directly on Apple's hypervisor and virtio-net stack, eliminating translation overhead for near-native execution speed on M-series processors.

OCI compatibility ensures your existing investments remain intact. Because container consumes and produces standard OCI images, your current Dockerfiles and build caches transfer without modification, as documented in the repository's README.md.

Simplified architecture reduces complexity. Written in Swift and leveraging the Containerization package for low-level container handling, the tool installs via a signed package that places the binary at /usr/local/bin/container and registers a system service automatically.

Pre-Migration Steps

Uninstall Docker Desktop

Remove Docker Desktop completely to free system resources and avoid conflicts with the container service. Drag the application to Trash or use the command-line helper:

/Applications/Docker.app/Contents/MacOS/Docker --uninstall

This removes the com.docker.vmnetd background service, which reserves network resources that container will manage natively through the hypervisor.framework.

Clean Up Docker Artifacts

Reclaim disk space by pruning Docker's storage and removing its data directory:

docker system prune -a
rm -rf ~/Library/Containers/com.docker.docker

Anonymous volumes created by Docker Desktop do not automatically migrate to container, so backing up important data before this step is essential.

Installing Apple Container

Download the latest signed installer package from the GitHub releases page. Double-click the .pkg file to install the binary to /usr/local/bin/container and register the container-system launch daemon.

Start the service manually if needed:

sudo container system start

Verify the installation:

container --version

# Example output: container 0.4.1 (2024-06-20)

For upgrades, use the bundled script referenced in scripts/update-container.sh:

/usr/local/bin/update-container.sh

Command Mapping and Daily Workflow

Building Images

Replace docker build with container build. Your Dockerfiles require zero changes:

# Docker Desktop

docker build -t my-app:latest .

# Apple Container

container build -t my-app:latest .

All standard flags from docs/command-reference.md are supported, including -f, --build-arg, --platform, and --memory. The build process utilizes the same BuildKit implementation as Docker, preserving cache behavior.

Running Containers

The container run command accepts identical options to docker run, with additional Apple-specific flags:

# Docker Desktop

docker run -p 8080:80 my-app

# Apple Container

container run -p 8080:80 my-app

Enable Rosetta 2 translation for x86 images using the --rosetta flag:

container run --rosetta -p 8080:80 my-app

Configuration Management

Unlike Docker Desktop's daemon JSON and ~/.docker directory, container stores system configuration in a TOML file:

<installRoot>/etc/container/config.toml

Edit this file to adjust default network settings, kernel installation behavior, or storage locations, as detailed in docs/tutorials/container-system-config-tutorial.md.

Advanced Migration Scenarios

Multi-Platform Builds

Build for both ARM64 and AMD64 architectures simultaneously using the --platform flag, which supersedes separate --os and --arch flags:

container build \
    --platform linux/arm64,linux/amd64 \
    -t my-app:latest \
    .

Volume and Networking Differences

Anonymous volumes (created with -v without a host path) behave differently in container—they are not automatically removed when containers are deleted. Manually clean these up to avoid orphaned storage.

Named volumes function identically to Docker Desktop, stored within the container's VM filesystem.

Custom Init Images

Use the --init-image flag to run custom VM-level initialization logic before your OCI container starts:

container run \
    --init-image local/custom-init:latest \
    -p 8080:80 \
    my-app:latest

This Apple-specific feature, documented in docs/command-reference.md, enables advanced networking or security setups that run prior to your application.

Summary

• Uninstall Docker Desktop completely, including the com.docker.vmnetd service, before installing container.
• Install via signed package to place the binary at /usr/local/bin/container and register the system service.
• Replace docker with container in your CLI commands—Dockerfiles and build caches remain compatible.
• Adjust configuration paths from ~/.docker to <installRoot>/etc/container/config.toml.
• Manage anonymous volumes manually, as they persist after container removal unlike Docker's behavior.
• Leverage Apple-specific flags like --rosetta for x86 translation and --init-image for custom VM initialization.

Frequently Asked Questions

Is Apple Container a full replacement for Docker Desktop?

Yes, for container runtime operations. The container CLI provides build, run, and image management capabilities using the same OCI standards as Docker Desktop. However, it lacks Docker Desktop's GUI and Kubernetes integration, focusing instead on lightweight, command-line driven workflows optimized for Apple Silicon.

Can I use my existing Dockerfiles without modification?

Absolutely. container processes standard Dockerfile syntax and produces OCI-compatible images. According to the README.md, your existing build scripts require only the command name change from docker to container—all flags and caching behavior remain identical.

How do I enable Rosetta 2 for x86 containers?

Append the --rosetta flag to your container run command. This activates Rosetta translation inside the lightweight VM, allowing x86 Linux containers to execute on ARM-based Apple Silicon Macs with performance superior to traditional QEMU emulation.

Where does Apple Container store its configuration?

System-wide configuration resides in <installRoot>/etc/container/config.toml rather than Docker's daemon JSON. User-specific settings and image storage are managed within the container service's VM filesystem, accessible through the CLI rather than direct file manipulation in most cases.

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