Prerequisites

You need

macOS 26 or later
Apple Silicon Mac (M1/M2/M3/M4)
Homebrew installed
Terminal access

You don't need

Docker Desktop (uninstall it now, or keep both — they coexist)
Xcode or developer tools beyond what Homebrew requires
A paid license — Apple Container is free

Step 1: Install Apple Container

brew install container

This installs the container CLI. Verify with:

container version

Expected output: version string with build info. If you see command not found, restart your terminal or run brew link container.

Step 2: Start the Container System

container system start

This initializes the Virtualization.framework backend. You'll be prompted for your password once — Apple Container needs it to create VMs.

If you're prompted about a default kernel, say yes — it'll download the Kata Containers kernel (~30 seconds).

Verify the system is running:

container system status

Troubleshooting: If It Didn't Work

These are the 4 most common first-run failures — pulled from GitHub issues and community reports. If yours isn't here, the production manual covers 14 more installation edge cases.

"No default kernel configured" prompt

Apple Container needs a Linux kernel. Say yes to the prompt — it'll download the Kata Containers kernel (3.17.0+). Takes ~30 seconds on a fast connection. If you accidentally said no, run container system stop && container system start to trigger the prompt again.

"Connection refused" when accessing your container

Apple Container needs Local Network access to assign IPs. Open System Settings → Privacy & Security → Local Network and enable your terminal app. Then restart the container system: container system stop && container system start.

"container system start" crashes with a fatal error

Check that ~/Library/Application Support/com.apple.container/ is writable. If you migrated from macOS 15 or an earlier beta, the app-root directory may have stale permissions. Run container system stop && container system start --reset to reinitialize. (GitHub #1802)

On macOS 15? Container-to-container networking is limited

macOS 15 has severely limited networking features for Apple Container. DNS-based service discovery (name.dev.internal) may not work. Upgrade to macOS 26+ for full functionality — this entire guide assumes macOS 26 or later. If you're stuck on macOS 15, stick with Docker Desktop for multi-container setups.

Still stuck? The production manual covers 14 more installation edge cases with exact error messages and verified fixes — kernel download failures, Local Network permission workflow, app-root crashes, and macOS version-specific issues. Get the Manual — $19 →

Step 3: Configure DNS

Apple Container uses its own DNS domain for inter-container communication. Set it once:

container system property set dns.domain dev.internal

This means containers can reach each other at container-name.dev.internal — no port mapping needed. Each container gets its own IP on the virtual network.

Key difference from Docker: No -p 8080:80 port mapping. In Apple Container, each container has its own IP. You access it directly at <container-ip>:80 or via DNS at <name>.dev.internal:80.

Step 4: Pull and Run Your First Container

Pull an image from Docker Hub (OCI compatible):

container pull nginx:latest

Run it:

container run --name my-nginx nginx:latest

Check it's running:

container ps
CONTAINER ID   NAME       IMAGE          STATUS    IP
abc123def456   my-nginx   nginx:latest   running   10.0.0.2

Access it at http://10.0.0.2 or http://my-nginx.dev.internal — you should see the Nginx welcome page.

Docker → Apple Container Command Cheat Sheet

Action	Docker	Apple Container
List containers	`docker ps`	`container ps`
Run a container	`docker run -d --name X image`	`container run --name X image`
Stop a container	`docker stop X`	`container stop X`
Remove a container	`docker rm X`	`container rm X`
View logs	`docker logs X`	`container logs X`
Execute in container	`docker exec -it X sh`	`container exec X sh`
Pull an image	`docker pull image`	`container pull image`
List images	`docker images`	`container images`
Bind mount	`-v /host/path:/container/path`	`--mount type=bind,src=/host/path,dst=/container/path`
Named volume	`-v vol_name:/path`	`--mount type=volume,src=vol_name,dst=/path`
Environment variable	`-e KEY=val`	`--env KEY=val`

Free Docker → Apple Container Cheat Sheet

One-page PDF with every common Docker command mapped to its Apple Container equivalent. Plus we'll ping you when Compose support ships — no spam, just that one email.

No spam. Just the cheat sheet + one notification when Compose launches.

Next: Solve the Compose Problem

You've got a single container running. Now let's handle multi-container setups — without compose.

Compose Alternative →

Install Apple Container & Run Your First Container