Apple Container vs Docker: Compose, Networking and Migration

Apple Container can replace part of a Mac development workflow. Running the same image does not mean every Docker tool will work. The useful migration question is not whether Alpine starts. It is whether your builds, service discovery, persistent data, tests and editor still behave correctly after the runtime changes.

This guide reviews Apple Container 1.4.1, released on 9 September 2026, the latest published release checked on 28 September 2026. That release includes two Containerization security fixes. The examples below are checked against tagged documentation and source, not a hands-on Mac benchmark. An installed CLI and a successful first run are not evidence that an entire development stack has migrated.

What is Apple Container, and which Macs does it support?

Apple's container is an open-source command-line tool, written in Swift, for building and running Linux containers in lightweight virtual machines on a Mac. Containerization is the underlying Swift package; container is the ready-to-use CLI. The 1.4.1 README specifies an Apple-silicon Mac and macOS 26 as the supported baseline. Do not treat older macOS compatibility notes as equivalent support, or confuse an Intel Linux image with support for an Intel Mac.

The tool consumes and produces OCI-compatible images. That makes image reuse possible across compatible runtimes and registries, subject to the image's operating system, architecture and runtime requirements. It does not promise Docker API compatibility. “Native on macOS” describes the host tooling and platform integration, not Linux processes running directly on the macOS kernel.

Apple Container vs Docker Desktop: what actually changes?

For ordinary container run workloads, Apple's technical overview describes a separate lightweight Linux VM per container. The Mac-side CLI talks to an API service and helpers through Apple's platform facilities. There is still a Linux kernel and a virtualization layer; this is not a VM-free implementation.

Docker Desktop's VMM documentation describes its Linux-VM backends on macOS, including Apple Virtualization framework and Docker VMM options. Do not reduce the comparison to “Docker emulates everything, Apple runs everything natively.” The relevant difference is the execution architecture, its isolation boundaries, and the tools each runtime exposes. CPU architecture and the selected backend also matter.

A VM boundary can help contain a compromised guest. It does not protect a host directory that you deliberately mount writable, or revoke credentials you forward into the guest. For a broader deployment-level threat model, use our Linux infrastructure guide for AI agents. This article stays with the Mac runtime migration.

Does Apple Container support Docker Compose and the Docker API?

Do not treat the core Apple CLI as a drop-in Docker Engine endpoint. The reviewed 1.4.1 command registry includes container, image, machine, volume, network and system commands, plus plugin dispatch. It does not register a built-in Compose command. That is a statement about this release's core CLI, not a claim that no third-party integration can exist.

Docker Compose defines and operates multi-container applications from a YAML model. Replacing a few docker run commands is a smaller migration than preserving a Compose application's networks, health checks, dependency conditions, profiles and teardown behavior. Do not solve that difference with alias docker=container: a command alias cannot implement a missing API or reproduce orchestration semantics.

For example, Testcontainers for Java requires a Docker-API-compatible runtime. Starting a database manually through Apple Container does not prove that Testcontainers can discover, provision, inspect and clean it up. Keep an engine already supported by your test setup until those tests pass with the proposed replacement.

Likewise, VS Code's alternative Docker setup documentation distinguishes Docker-compatible command-line workflows from other container engines. Validate your exact Dev Containers extension, runtime adapter, Features, mounts and Compose usage. A terminal that can run an image is not an end-to-end editor compatibility test.

How to install Apple Container without replacing your current runtime

Download the signed installer package from the release linked above and install it following Apple's instructions. The installer requests administrator permission to place files under /usr/local. You do not need to build the Swift project just to use that package. Keep your current Docker environment and its data during the pilot.

On the Mac, check the OS and architecture, then start the service. uname -m should report arm64 for a native Apple-silicon terminal. Apple's CLI rejects being run under Rosetta; that is separate from its ability to translate an amd64 guest application.

sw_vers -productVersion
uname -m
container --version
container system start
container system status
container run --rm docker.io/library/alpine:3.22 echo "container ready"

The initial image pull needs registry access. Startup may also require preparing the Linux kernel. If this step fails, check the system status and network access before debugging your application. Use the installed version's help rather than copying flags from a different release.

Can Apple Container build an existing Dockerfile?

Yes. The 1.4.1 command reference documents container build using BuildKit, with Dockerfile support and a Containerfile fallback. It also documents build arguments, targets, secrets and platform selection. This is support for a build interface, not proof that every Buildx workflow or plugin is interchangeable.

Here is a minimal local web-server example. Run it in a new directory; the image tags are readable examples, not immutable production pins. Use reviewed image digests for reproducible team baselines. This Python server is for the local smoke test, not a production serving recommendation.

mkdir apple-container-demo
cd apple-container-demo
printf '%s\n' 'Apple Container is serving this page.' > index.html
cat > Dockerfile <<'EOF'
FROM docker.io/library/python:3.13-alpine
WORKDIR /srv
COPY index.html .
EXPOSE 8000
CMD ["python", "-m", "http.server", "8000", "--bind", "0.0.0.0"]
EOF
container build -t wavect/container-demo:local .
container run -d --name wavect-web --cpus 2 --memory 512M \
  --publish 127.0.0.1:8080:8000 wavect/container-demo:local
curl --fail http://127.0.0.1:8080/
container logs wavect-web

The server listens on 0.0.0.0 inside the guest so forwarding can reach it. The published Mac address is explicitly 127.0.0.1, keeping that forwarded listener on IPv4 loopback. This does not define a complete firewall policy for every path to the VM. Passing curl proves the host-to-container HTTP path, not inter-container DNS, database persistence or editor compatibility.

Why does localhost work differently after a Docker migration?

There are three distinct connection paths. Apple's networking guide documents container IP addresses, loopback port publishing and DNS configuration. Test each path separately instead of changing unrelated firewall settings.

For domain-qualified names, merge the following into ~/.config/container/config.toml, preserving existing settings. Do not create a second [dns] table if one exists:

[dns]
domain = "test"

Restarting the service affects running workloads, so stop or schedule them first. Register the domain with the macOS resolver only when that local DNS change is intended:

container system stop
container system start
sudo container system dns create test

These steps configure the service and the Mac resolver. Once the demo is running again, its name is wavect-web.test and its guest port is 8000. The reviewed guide warns that bare-hostname discovery on custom networks is not equivalent to Compose service discovery; use the documented domain-qualified path on the default network or inspect container IPs for the custom-network case.

For the reverse direction, Apple's host-integration guide documents an optional --localhost DNS setup. It warns that this setup disables Private Relay and that its packet-filter rule is removed on restart. Do not silently replace host.docker.internal in a team script with a host-network change that has different side effects. Review the intended setup with the people responsible for the Mac and its network policy.

Do Apple Container volumes preserve data like Docker volumes?

Apple supports named volumes, bind mounts and tmpfs, but the lifecycles are not identical. The 1.4.1 volume guide describes named volumes backed by sparse filesystem images and notes that anonymous volumes are not automatically deleted by --rm. A container disappearing does not prove all its data disappeared.

This probe writes to an explicitly named volume, removes the first container on exit, and reads from another container using a read-only mount:

container volume create wavect-demo-data
container run --rm --volume wavect-demo-data:/data \
  docker.io/library/alpine:3.22 \
  sh -c 'printf "persistent\n" > /data/probe.txt'
container run --rm --volume wavect-demo-data:/data:ro \
  docker.io/library/alpine:3.22 cat /data/probe.txt

The expected application output from the final command is persistent. This is a proposed acceptance check, not a result measured here. The volume remains after the check. For a database, also test writes through its real client, clean shutdown, restart and recovery. Preserve the database version and use its supported backup/restore procedure when moving data between runtimes; do not assume a Docker-managed volume name refers to the same storage in Apple Container.

Do not run volume pruning as a routine troubleshooting step. Apple's guide warns that unreferenced volumes and their contents are deleted immediately. Keep migration backups until you have verified restoration. Prefer narrow, read-only bind mounts for source inspection; give write access only where the workflow needs it.

Can Apple Container run amd64 images and build for Linux servers?

Apple's multiplatform image guide documents building both arm64 and amd64 variants. The amd64 user-space program runs under Rosetta translation on Apple silicon. That does not turn the Mac into an Intel host or make the guest an independently validated x86 production environment.

container build --arch arm64 --arch amd64 \
  --tag wavect/container-demo:multi .
container run --rm --arch amd64 wavect/container-demo:multi uname -m

Run this from the earlier demo directory. Rosetta must be available for the translated execution path. Reaching uname -m is only an architecture smoke test: native dependencies, database extensions, system calls and performance still need workload-level checks. Keep a target-architecture CI job even when the local image builds successfully.

Does Apple Container now have Kubernetes and persistent Linux machines?

Yes, the reviewed release documents a local Kubernetes workflow through container k8s. It creates development clusters, can load locally built images and works with kubectl. Older blanket statements that Apple Container has no Kubernetes workflow are therefore misleading for this release.

container k8s create --name wavect-local
container k8s list
kubectl --context wavect-local get nodes

This optional example requires kubectl and creates a local cluster. The tooling updates ~/.kube/config; use the explicit context to avoid confusing it with a production cluster. A local Kubernetes workflow does not automatically provide a Compose implementation or Docker API compatibility.

There is also container machine, which provides persistent Linux environments rather than just a single application container. Its default home-directory integration is writable. That convenience has a different trust boundary from a narrowly mounted container run workspace. Do not hand an untrusted coding agent a home-shared machine while describing it as isolated from your personal files.

Is Apple Container faster or lighter than Docker Desktop?

There is no universal performance winner established by this article. Apple's resource guide documents per-container CPU and memory settings, a separate builder VM and usage statistics. A configured memory limit is not the same as current resident memory. The technical overview also documents partial memory-ballooning support: memory freed inside the Linux guest is not necessarily returned to macOS.

container stats --no-stream
container system df
container builder stop

Stop the builder only after builds are finished. Measure cold start including image pulls separately from warm starts with cached images. Compare identical image digests, CPU architecture, resource limits, mount type and workload. Observe the complete host process group, macOS memory pressure and swap, not just a number printed inside the guest. Also record what remains after containers and builders stop.

Our proposed decision metric is time to a verified working environment: installation, image build, application readiness, test completion and recovery after a restart. A faster empty-container launch is not useful if developers lose more time fixing DNS or incompatible tooling.

Common migration failures and the smallest useful check

When should a team switch, and when should it retain Docker?

Start with one disposable service or build job, not an organization-wide uninstall. Apple Container is worth evaluating when the target is an Apple-silicon Mac and the work is directly expressed through supported image, build and container commands. Retain your current runtime for workflows whose required Compose, Docker API or editor integration has not passed acceptance testing. Different developers can use different local tools while the team shares an OCI image and a CI contract.

When the HTTP demo is no longer needed, stop and remove only its named container:

container stop wavect-web
container delete wavect-web

The named test volume, built images and optional Kubernetes cluster are separate resources. Review them individually rather than using a blanket prune command. No command above deletes your existing Docker data.

For application-level acceptance, use our software QA checklist. For an agent execution service rather than a Mac CLI, see the separate OpenSandbox architecture review. The tool should follow the workload and trust boundary, not the other way around.