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

> Migrate from Docker Desktop to Apple Container on Apple Silicon Macs. Uninstall Docker Desktop, install container, and replace docker commands with container for native Linux container performance.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: migration-guide
- Published: 2026-07-04

---

**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 `Dockerfile`s and build caches transfer without modification, as documented in the repository's [`README.md`](https://github.com/apple/container/blob/main/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:

```bash
/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:

```bash
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](https://github.com/apple/container/releases). 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:

```bash
sudo container system start

```

Verify the installation:

```bash
container --version

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

```

For upgrades, use the bundled script referenced in [`scripts/update-container.sh`](https://github.com/apple/container/blob/main/scripts/update-container.sh):

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

```

## Command Mapping and Daily Workflow

### Building Images

Replace `docker build` with `container build`. Your `Dockerfile`s require zero changes:

```bash

# Docker Desktop

docker build -t my-app:latest .

# Apple Container

container build -t my-app:latest .

```

All standard flags from [`docs/command-reference.md`](https://github.com/apple/container/blob/main/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:

```bash

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

```bash
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:

```bash
<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`](https://github.com/apple/container/blob/main/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:

```bash
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:

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

```

This Apple-specific feature, documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/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—`Dockerfile`s 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`](https://github.com/apple/container/blob/main/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.