# How to Migrate from Docker Desktop to Container on Apple Silicon Macs > Easily migrate from Docker Desktop to container on Apple Silicon Macs. Uninstall Docker Desktop, install the signed container package, and switch your commands. Keep your Dockerfiles and images. - Repository: [Apple/container](https://github.com/apple/container) - Tags: migration-guide - Published: 2026-06-20 --- **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 `Dockerfile`s 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: ```bash # 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](https://github.com/apple/container/releases). 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: ```bash sudo container system start ``` ### Verify the Installation Check that the binary is correctly installed and accessible: ```bash 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: ```bash /usr/local/bin/update-container.sh ``` ### Build and Run Your First Container Your existing `Dockerfile`s require zero changes. Simply replace the `docker` command with `container`: **Building images:** ```bash # 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`](https://github.com/apple/container/blob/main/docs/command-reference.md). It uses the same BuildKit implementation as Docker, so your build cache transfers directly. **Running containers:** ```bash # 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: ``` /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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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: ```bash 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: ```bash 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 `/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 `/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`](https://github.com/apple/container/blob/main//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.