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

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, 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 (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. 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 (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:

container system start

This command creates the default vmnet network and initializes the builder VM infrastructure, as detailed in 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:

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

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

This configuration persists for the build session, as documented in 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:

# 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 (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 (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 (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.

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