How to Migrate from Docker Desktop to Apple Container on Apple Silicon Macs

You can migrate from Docker Desktop to Apple Container by uninstalling Docker Desktop, installing the signed container package from the apple/container repository, and replacing docker commands with container in your existing workflows—all while maintaining full OCI image compatibility.

Apple Container is an open-source runtime built specifically for macOS that leverages Apple’s native virtualization stack to run Linux containers on M-series chips. Unlike Docker Desktop, which relies on additional translation layers, container executes workloads directly through the Apple hypervisor and virtio-net stack, delivering near-native performance on Apple Silicon.

Why Migrate to Apple Container?

Migrating to container offers specific technical advantages for macOS users, particularly those on M1, M2, or M3 processors.

• Native Apple Silicon Optimization – The runtime uses Apple’s hypervisor framework and virtio-net networking stack, eliminating the performance overhead associated with cross-architecture emulation according to the README.md source.
• OCI Image Compatibility – Apple Container consumes and produces standard OCI images, meaning your existing Dockerfiles and image registries work without modification.
• Swift-Based Architecture – The tool is implemented in Swift and leverages the Containerization Swift package for low-level container, image, and process handling, providing tighter integration with macOS system services.
• Simplified Service Management – The installer registers a system service automatically, placing the binary at /usr/local/bin/container and configuring the container-system launch-daemon.

Prerequisites and Installation

Remove Docker Desktop

Before installing Apple Container, you must completely remove Docker Desktop to avoid port conflicts and resource contention.

If Docker Desktop was installed via the GUI:

# Quit Docker Desktop first, then run:

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

Alternatively, drag the Docker app to Trash. This also removes the background service (com.docker.vmnetd) that reserves network resources, freeing them for container.

Install Apple Container

Download the latest signed installer package from the GitHub releases page of the apple/container repository. Double-click the .pkg file to install.

The installer performs three actions documented in README.md:

1. Writes the binary to /usr/local/bin/container
2. Registers the container-system launch-daemon
3. Starts the service automatically

If you need to start the service manually:

sudo container system start

Verify the Installation

Confirm the binary is correctly installed and accessible:

container --version

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

If upgrading from a previous version of container, use the bundled update script referenced in the repository:

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

Migrating Your Workflow

Building Images

Your existing Dockerfiles require zero modifications. Replace docker build with container build:

# Docker Desktop command:

docker build -t my-app:latest .

# Apple Container equivalent:

container build -t my-app:latest .

According to the command-reference.md source, container build supports the same flags as Docker, including -f for alternative Dockerfiles, --build-arg for build-time variables, and --platform for multi-architecture builds. The implementation uses the same BuildKit engine, so build caching behavior remains identical.

Running Containers

The container run command accepts standard Docker options while adding Apple-specific enhancements:

# Docker Desktop:

docker run -p 8080:80 -d my-app:latest

# Apple Container:

container run -p 8080:80 -d my-app:latest

For x86_64 images on Apple Silicon, use the --rosetta flag to enable Rosetta 2 translation inside the VM:

container run --rosetta -p 8080:80 my-x86-image:latest

As documented in command-reference.md, you can also specify custom VM-level initialization logic using the --init-image flag, which runs before your OCI container starts.

Configuration File Locations

Docker Desktop stores daemon configuration in ~/.docker and JSON files. Apple Container uses a TOML configuration file located at:

<installRoot>/etc/container/config.toml

Refer to tutorials/container-system-config-tutorial.md in the repository to adjust default network settings, kernel installation behavior, or storage locations. If you previously customized Docker daemon settings, you must manually migrate those values to this TOML format.

Volume and Networking Considerations

Named volumes function identically between the two runtimes. However, anonymous volumes (created with -v without a host path) behave differently:

• Apple Container does not auto-remove anonymous volumes when deleting containers. You must prune them manually.
• Both systems store volume data within the VM filesystem, but the underlying storage paths differ since container uses Apple’s virtualization storage stack.

Advanced Migration Features

Multi-Architecture Builds

Build for both arm64 and amd64 targets simultaneously using the --platform flag, which supersedes the separate --os and --arch flags mentioned in command-reference.md:

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

Custom Init Images

For specialized initialization requirements, specify a custom init image:

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

This feature, implemented in the Swift-based runtime, allows you to execute VM-level setup before the primary container process starts.

Summary

• Uninstall Docker Desktop completely using the uninstaller or GUI before installing Apple Container to prevent service conflicts.
• Install via the signed .pkg from the apple/container releases page, which places the binary at /usr/local/bin/container and configures the system service.
• Replace docker with container in your CLI commands; all standard flags for build, run, and image management remain compatible.
• Migrate configuration settings from Docker’s JSON files to /etc/container/config.toml if you used custom daemon options.
• Use --rosetta for x86_64 image compatibility and --init-image for custom VM initialization sequences.

Frequently Asked Questions

Is Apple Container fully compatible with Docker Compose files?

Apple Container focuses on the core OCI runtime and CLI. While it handles Dockerfile builds and standard container run operations, Docker Compose (the multi-container orchestration tool) is not included in the base container package. You would need to manage multi-container deployments using alternative orchestration methods or wait for future Compose-compatible tooling from the project.

How does performance compare to Docker Desktop on Apple Silicon?

Because container runs Linux containers inside lightweight virtual machines built directly on Apple’s hypervisor and virtio-net stack—without the additional abstraction layers Docker Desktop requires—it delivers near-native performance on M-series chips. The Swift-based implementation in the Containerization package also minimizes overhead compared to Docker’s cross-platform architecture.

Can I use Rosetta to run x86_64 containers?

Yes. Apple Container includes native Rosetta 2 support via the --rosetta flag when running containers. This allows you to execute x86_64 Linux images on Apple Silicon Macs with translation handled efficiently within the VM, rather than through slower user-mode emulation.

How do I completely uninstall Apple Container if I need to revert?

Run the provided uninstall script located at /usr/local/bin/uninstall-container.sh. By default, this removes the binary and service registration while preserving user data. Add the -k flag to keep configuration files, or omit it to remove all traces of the installation, as documented in the repository’s README.md.

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