# How to Migrate from Docker or Podman to Apple container: A Complete Migration Guide

> Migrate from Docker or Podman to Apple container in minutes. Discover a seamless transition with this complete guide, leveraging the same OCI image and Dockerfile formats.

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

---

**Apple's `container` CLI is a drop-in replacement for Docker and Podman that uses the same OCI image format and Dockerfile syntax, requiring only command prefix changes from `docker` to `container` for most workflows.**

This guide covers the complete migration path from Docker or Podman to the Apple `container` project, an open-source container runtime designed specifically for macOS 26+ on Apple Silicon. Because `container` implements the OCI specification, you can migrate existing container workflows without modifying image formats or build definitions.

## Architecture Differences Between Docker and Apple container

Understanding the architectural shift helps clarify why certain commands behave differently despite similar syntax.

### Image Format Compatibility

Both Docker and Apple `container` use the **OCI (Open Container Initiative)** image format. According to the source code in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), any Docker image stored in a registry can be pulled and executed without conversion. The default registry remains Docker Hub (`docker.io`) for image references without an explicit host, ensuring existing `FROM` statements in Dockerfiles work immediately.

### Build Engine Isolation

While Docker uses BuildKit with a client-daemon model, Apple `container` implements a **builder VM** architecture. As documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 20-28), the build process runs inside a lightweight utility container within an Apple Silicon hypervisor-managed VM. This provides stronger isolation than Docker's daemon-based approach while maintaining BuildKit compatibility.

### Runtime Isolation Model

Docker on macOS runs Linux containers through a Linux VM or Docker Desktop's virtualization layer. In contrast, `container` executes all workloads inside a **lightweight virtual machine** managed by the `container` system service, as implemented in [`Sources/ContainerPlugin/ServiceManager.swift`](https://github.com/apple/container/blob/main/Sources/ContainerPlugin/ServiceManager.swift). This VM leverages the native Apple Silicon hypervisor for improved performance and security boundaries.

## Step-by-Step Migration Process

Follow these steps to transition your development workflow from Docker or Podman to Apple `container`.

### 1. Install the container CLI

Download the signed installer from the GitHub releases page or use the provided update script referenced in [`README.md`](https://github.com/apple/container/blob/main/README.md) (lines 24-33). The tool requires macOS 26 or later running on Apple Silicon hardware.

### 2. Initialize the System Service

Start the background service that manages VM lifecycle and networking:

```bash
container system start

```

This command creates the default `vmnet` network and initializes the builder VM infrastructure, as detailed in [`README.md`](https://github.com/apple/container/blob/main/README.md) (lines 28-33).

### 3. Translate Core Commands

Replace the `docker` or `podman` prefix with `container` for most operations. The CLI maintains identical sub-command names:

```bash

# Build an image

container build -t myapp:latest .

# Run a container

container run -d --name myapp -p 8080:80 myapp:latest

# Execute commands inside running containers

container exec -it myapp /bin/sh

# Push to registries (note the 'image' sub-command requirement)

container image push docker.io/username/myapp:latest

```

### 4. Configure Builder Resources for Large Builds

The default builder VM allocates 2 GiB RAM and 2 CPUs. For resource-intensive builds, scale the builder before starting:

```bash
container builder start --memory 8g --cpus 8

```

This configuration persists for the build session, as documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 18-28).

## Command Reference: Docker to container Mapping

While most commands map identically, note these specific translations:

| Docker / Podman | Apple container | Key Differences |
|-----------------|----------------|-----------------|
| `docker build -t img .` | `container build -t img .` | Identical syntax; automatically discovers `Dockerfile` or `Containerfile` |
| `docker run -v $HOME/data:/data img` | `container run --volume $HOME/data:/data img` | Same colon-separated host:container path syntax |
| `docker push registry.com/img` | `container image push registry.com/img` | Requires explicit `image` sub-command |
| `docker compose up` | Not supported | Use individual `container` commands or shell scripts temporarily |

## Practical Migration Example

This complete workflow demonstrates migrating an existing Docker-based application:

```bash

# Start the service (run once per session or after reboot)

container system start

# Build from existing Dockerfile without modifications

container build -t webapp:latest .

# Run with port mapping and volume mounts

container run -d \
  --name webapp \
  -p 8080:80 \
  --volume $(pwd)/data:/app/data \
  webapp:latest

# Verify the container is accessible

curl http://localhost:8080

# Push to Docker Hub (default registry)

container image push docker.io/username/webapp:latest

```

The `container` CLI reads the same Dockerfile syntax and environment variables. As noted in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 307), registry authentication and image inspection commands maintain parity with Docker workflows.

## Volume and Persistence Considerations

One critical behavioral difference involves volume cleanup. Unlike Docker's `--rm` flag behavior which auto-removes anonymous volumes, Apple `container` does **not** automatically clean up anonymous volumes when containers are removed. According to [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 924), you must manually delete unused volumes to reclaim disk space.

## Configuration Files and Registry Defaults

Customize registry endpoints and builder settings in `~/.config/container/config.toml`, as referenced in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 66-70). The default configuration points to Docker Hub (`docker.io`), maintaining consistency with standard Docker installations.

## Summary

- **Apple `container` uses standard OCI images**, ensuring full compatibility with existing Docker Hub registries and local images.
- **Command syntax is nearly identical** to Docker, requiring only prefix changes from `docker` to `container` and explicit `image` sub-commands for push/pull operations.
- **Builder VMs require explicit resource allocation** using `container builder start --memory` and `--cpus` for large builds, unlike Docker's daemon configuration.
- **Anonymous volumes persist** after container removal and require manual cleanup.
- **Docker Compose is not yet supported**, requiring temporary workarounds using shell scripts or individual commands.

## Frequently Asked Questions

### Is apple/container compatible with my existing Docker images?

Yes. Apple `container` implements the OCI image specification and can pull, run, and build images from any Docker-compatible registry. The default registry remains Docker Hub (`docker.io`), and the `container image inspect` command produces output matching Docker's manifest format.

### How do I increase memory and CPU for container builds?

Use the `container builder start` command with resource flags before building. For example, `container builder start --memory 8g --cpus 8` allocates 8 GB of RAM and 8 CPU cores to the builder VM. This differs from Docker, which requires daemon-level configuration changes.

### Does apple/container support Docker Compose?

No. Docker Compose support is marked as future work in the project roadmap. Current workflows require either individual `container` commands or temporary shell scripts to orchestrate multi-container applications.

### What platforms can run apple/container?

Apple `container` requires macOS 26 or later running exclusively on Apple Silicon hardware (M1/M2/M3 or later). The runtime leverages the Apple Silicon hypervisor for VM management and does not support Intel-based Macs or Linux hosts.