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

To migrate from Docker Desktop to container on Apple Silicon Macs, uninstall Docker Desktop, install the signed container package from Apple's releases page, then replace docker commands with container commands while keeping your existing Dockerfiles and OCI images unchanged.

The apple/container repository provides a native container runtime built specifically for macOS. Written in Swift and leveraging Apple's hypervisor and virtio-net stack, it offers near-native performance on M-series chips while maintaining full OCI compatibility with your existing Docker workflows.

Why Migrate from Docker Desktop to Container?

Native Apple Silicon support eliminates the translation layers common in other virtualization solutions. The container tool runs Linux containers inside lightweight virtual machines built directly on Apple's virtualization framework, giving you near-native performance on M-series chips according to the repository's README.

Full OCI compatibility means your existing Dockerfiles work without modification. The tool consumes and produces OCI images exactly like Docker, so you can migrate your build pipelines without rewriting container definitions.

Simplified architecture replaces the Docker daemon with a Swift-based implementation that uses the Containerization Swift package for low-level container, image, and process handling. A signed installer package places the binary under /usr/local/bin and registers a system service automatically.

Step-by-Step Migration Guide

Uninstall Docker Desktop

First, remove Docker Desktop to free up system resources and network interfaces.

If you installed Docker Desktop via the GUI:

# Quit Docker Desktop from the menu bar, then run:

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

Removing Docker Desktop also eliminates its background service (com.docker.vmnetd), which frees the reserved network resources for container.

Install Apple Container

Download the latest signed installer from the GitHub releases page. Double-click the .pkg file to install.

The installer performs three actions automatically:

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

If you need to start the service manually after installation:

sudo container system start

Verify the Installation

Check that the binary is correctly installed and accessible:

container --version

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

If you have an older version of container installed, upgrade using the bundled script:

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

Build and Run Your First Container

Your existing Dockerfiles require zero changes. Simply replace the docker command with container:

Building images:

# Docker Desktop command:

docker build -t my-app:latest .

# Apple Container equivalent:

container build -t my-app:latest .

The container build command supports all common flags including -f, --build-arg, --platform, and --memory, as documented in docs/command-reference.md. It uses the same BuildKit implementation as Docker, so your build cache transfers directly.

Running containers:

# Docker Desktop:

docker run -p 8080:80 my-app

# Apple Container:

container run -p 8080:80 my-app

Additional Apple-specific options are available, such as --rosetta to enable Rosetta translation inside the VM for x86 compatibility.

Configure System Settings (Optional)

container stores its system configuration in a TOML file located at:

<installRoot>/etc/container/config.toml

You can edit this file to change default network settings, kernel installation behavior, or storage locations. See docs/tutorials/container-system-config-tutorial.md for detailed configuration options.

Key Differences and Compatibility

Command syntax remains nearly identical. The CLI in docs/command-reference.md confirms that container build, container run, container push, and container pull accept the same flags as their Docker equivalents.

Volume handling differs slightly for anonymous volumes. While named volumes work identically, anonymous volumes created with -v (without a host path) are not auto-removed when you run container rm. Delete them manually if you need to reclaim space.

Multi-architecture builds use the standard --platform flag:

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

The --platform flag supersedes the separate --os/--arch flags mentioned in the command reference.

VM-level initialization offers an Apple-specific feature unavailable in Docker Desktop:

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

The --init-image flag lets you run custom VM-level init logic before the OCI container starts, as implemented in the Swift source.

Performance Benefits on Apple Silicon

Direct VM execution on Apple silicon removes the translation layer Docker Desktop uses for x86 images. The container tool leverages the Containerization Swift package for low-level operations, resulting in faster build times and reduced memory overhead compared to cross-platform virtualization solutions.

The service runs with minimal privileges and uses signed packages, improving your security posture while maintaining compatibility with existing OCI registries.

Summary

• Uninstall Docker Desktop using its built-in uninstaller or by dragging to Trash, then remove residual data from ~/Library/Containers/com.docker.docker.
• Install container via the signed .pkg from the releases page, which places the binary at /usr/local/bin and registers the system service.
• Keep your Dockerfiles—the OCI-compatible runtime accepts identical syntax and build arguments.
• Replace commands by changing docker to container in your scripts and muscle memory.
• Configure via TOML at <installRoot>/etc/container/config.toml instead of Docker's JSON daemon configuration.

Frequently Asked Questions

Do I need to modify my Dockerfiles when migrating to container?

No. The container tool is fully OCI-compatible and accepts standard Dockerfile syntax without modification. Your existing build contexts, multi-stage builds, and ARG instructions work identically, as confirmed in the repository's README and command reference documentation.

Where does container store its configuration?

Configuration resides in <installRoot>/etc/container/config.toml rather than Docker's JSON daemon configuration. This TOML file controls network settings, kernel installation behavior, and storage locations. You can edit it directly or use the CLI to manage system-level settings.

Can I run x86 containers on Apple Silicon with container?

Yes. Use the --rosetta flag when running containers to enable Rosetta translation inside the VM. This allows you to execute x86_64 Linux binaries on M-series chips, though native arm64 builds will always provide the best performance on Apple Silicon.

How do I completely remove container if I need to revert?

Run the bundled uninstall script located at /usr/local/bin/uninstall-container.sh. The script accepts a -k flag to preserve user data while removing the binary and system service, ensuring clean removal without leftover launch daemons.

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