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

> Easily migrate from Docker Desktop to Apple Container on Apple Silicon Macs. Uninstall Docker, install the container package, switch commands, and maintain OCI compatibility.

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

---

**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 `Dockerfile`s 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:

```bash

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

```bash
sudo container system start

```

### Verify the Installation

Confirm the binary is correctly installed and accessible:

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

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

```

## Migrating Your Workflow

### Building Images

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

```bash

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

```bash

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

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

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

```

### Custom Init Images

For specialized initialization requirements, specify a custom init image:

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