2026/10/15
Docker on macOS is a Linux VM in a trench coat
- Containers are a Linux thing
- Let’s catch it in the act
- The full picture
- 1. Your Mac has 10 cores. Your containers have 4.
- 2. Bind mounts cross the VM boundary on every syscall
- 3. localhost:8080 isn’t really your container
- 4. Your images live in one giant file
- 5. amd64 images get emulated
- “But I use OrbStack / Colima / Podman”
- Conclusions
I saw this post go by and realized that most people I’ve worked with have no idea that every container they run on their MacBook is actually running inside a virtual machine. Not “kinda like a VM”. An actual VM, with its own Linux kernel, its own RAM, its own disk image and its own network.
It sounds like trivia, but it explains a whole bunch of “why is Docker so slow on my Mac” and “why can’t I reach my container” moments. So let’s open the trench coat.
TL;DR: containers are a Linux kernel feature. macOS doesn’t run a Linux kernel, so Docker Desktop boots one in a VM and forwards everything (API calls, ports, files) across the VM boundary. That boundary is why bind mounts are ~100x slower than volumes, why your container sees 4 CPUs on a 10 core machine, and why amd64 images crawl on Apple silicon.
Everything below was measured on an M1 Pro (10 cores, 32 GB) running macOS 27 and Docker Desktop with engine 28.5.1, default settings. Numbers, not vibes.
Containers are a Linux thing
A container isn’t a thing the kernel knows about. It’s a regular process that the kernel lies to:
- namespaces make it believe it has its own PIDs, hostname, network interfaces and filesystem tree;
- cgroups cap how much CPU and memory it can eat;
- overlayfs stacks image layers into the root filesystem it sees.
All three are Linux kernel features. macOS runs XNU, which has none of them.
And a Linux binary inside an image (your node, your postgres) makes Linux
syscalls, which XNU doesn’t speak either. So there’s no way around it: to run
Linux containers you need a Linux kernel, and on a Mac the only way to get one
is to boot it in a VM.
Let’s catch it in the act
First hint, the client and the server don’t even agree on what OS they’re on:
$ docker version --format '{{.Client.Os}}/{{.Client.Arch}} -> {{.Server.Os}}/{{.Server.Arch}}'
darwin/arm64 -> linux/arm64
Ask a container which kernel it’s running on:
$ docker run --rm alpine uname -a
Linux 31b5b8c057ac 6.10.14-linuxkit #1 SMP Tue Oct 14 07:32:13 UTC 2025 aarch64 Linux
That’s not my Mac’s kernel (Darwin 27.0.0 ... xnu-13432). It’s linuxkit,
the tiny Linux distro Docker builds specifically to host its daemon.
Now look for the daemon on the Mac:
$ pgrep -lf dockerd
$ # nothing
There’s no dockerd on macOS at all. What there is, though:
$ ps -axo rss,comm | grep -i virtualization
1958288 /System/Library/Frameworks/Virtualization.framework/.../com.apple.Virtualization.VirtualMachine
A process from Apple’s Virtualization.framework, sitting on 1.9 GB of RAM with nothing running. That’s the VM.
We can even walk into it. A privileged container sharing the host PID namespace
can nsenter into PID 1, and “host” here means the VM, not your Mac:
$ docker run --rm --privileged --pid=host alpine \
nsenter -t 1 -m -u -n -i sh -c 'cat /etc/os-release; ps -o pid,args | grep -E "dockerd|containerd "'
PRETTY_NAME="Docker Desktop"
199 /usr/bin/containerd --config /etc/containerd/containerd.toml
219 /usr/local/bin/dockerd --config-file /run/config/docker/daemon.json ... --host-gateway-ip 192.168.65.254
There it is: a Linux box called docker-desktop, with the real dockerd and
containerd running inside it.
The full picture
dockerthe CLI you type intocom.docker.backendsocket proxy, port forwarder, network stackcom.apple.Virtualization.VirtualMachinethe VM itself, ~1.9 GB RSS idle
- API calls~/.docker/run/docker.sock → vsock → dockerd
- -p 8089:80com.docker.backend listens on the Mac, forwards into the VM
- -v ~/code:/appvirtiofs share of /Users, mounted at /host_mnt/Users
- images, volumesDocker.raw on your Mac disk = /dev/vda1 in the VM
dockerdthe actual Docker daemoncontainerdcontainer lifecycleruncnamespaces + cgroups
Your docker CLI talks to a unix socket on the Mac
(~/.docker/run/docker.sock). com.docker.backend picks that up and ships it
over vsock (a virtual socket between host and guest) to dockerd in the VM.
dockerd then does what it does on any Linux server: asks containerd and runc
to set up namespaces and cgroups for your process.
The hypervisor part is Apple’s Virtualization.framework (older Intel-era versions used HyperKit, and newer Docker Desktop versions also offer their own “Docker VMM”). The rest of this post is about the four dashed arrows in that diagram, because each one costs you something.
1. Your Mac has 10 cores. Your containers have 4.
The VM gets a fixed slice of your machine, set in Docker Desktop’s settings:
$ jq '{Cpus, MemoryMiB, DiskSizeMiB}' ~/Library/Group\ Containers/group.com.docker/settings-store.json
{ "Cpus": 4, "MemoryMiB": 2560, "DiskSizeMiB": 40960 }
$ docker run --rm alpine sh -c 'nproc; free -m | head -2'
4
total used free
Mem: 2411 589 1126
| Mac | What containers see | |
|---|---|---|
| CPUs | 10 | 4 |
| RAM | 32 GB | 2.4 GB |
So when your Java service gets OOM-killed locally with “plenty of RAM free”,
it’s not lying: the VM has 2.4 GB total, shared by every container you run. And
anything that sizes thread pools on nproc (the JVM, Go’s GOMAXPROCS, make -j$(nproc)) sizes itself for 4 cores, not 10.
The flip side: that 1.9 GB of RSS is taken from your Mac as soon as Docker Desktop starts, whether you run containers or not.
2. Bind mounts cross the VM boundary on every syscall
This is the one that hurts the most in day-to-day dev. When you
-v ~/code/app:/app, the files live on your Mac’s APFS disk, and the container
lives in the VM. Something has to bridge the two, and that something is
virtiofs:
$ docker run --rm --privileged --pid=host alpine nsenter -t 1 -m sh -c 'mount | grep Users'
virtiofs0 on /run/host_virtiofs/Users type virtiofs.virtiofs0 (rw,...)
/run/host_mark/Users on /host_mnt/Users type fakeowner (rw,...)
Every open, stat, write and unlink your container does on a bind-mounted
path becomes a request from the guest kernel to the host, served by macOS, and
answered back. Big sequential writes amortize that fine. Lots of small files
absolutely don’t. And “lots of small files” is exactly what node_modules,
.git, Python virtualenvs and build caches are.
I ran the same script on a bind mount, a named volume (lives on the VM’s own disk) and the container’s own filesystem:
| bind mount | named volume | ratio | |
|---|---|---|---|
| untar 20k small files | 14.6 s | 138 ms | 106x |
| rm 20k files | 7.6 s | 169 ms | 45x |
| stat 20k files | 1.0 s | 20 ms | 51x |
| write 512 MB + fsync | 452 ms | 503 ms | 0.9x |
Same data, same container, two orders of magnitude apart, depending only on which side of the VM the files live on. Sequential throughput is fine; metadata-heavy work is where the round trips pile up.
What to do about it:
- Keep dependency folders inside the VM: mount the source, but put
node_modules/.venv/targeton a named volume (-v app_modules:/app/node_modules). - Don’t bind-mount build caches. Use volumes or BuildKit cache mounts.
- If you’re on a paid plan, Docker Desktop’s “synchronized file shares” keep a copy inside the VM and sync it, which avoids most of the round trips.
3. localhost:8080 isn’t really your container
When you publish a port, who’s actually listening on your Mac?
$ docker run -d -p 8089:80 nginx:alpine
$ lsof -nP -iTCP:8089 -sTCP:LISTEN
COMMAND PID USER FD TYPE NODE NAME
com.docke 72599 me 145u IPv6 TCP *:8089 (LISTEN)
Not nginx. Not even dockerd. It’s com.docker.backend, a userspace proxy
that accepts the connection on the Mac and forwards it into the VM, where the
usual iptables/bridge magic routes it to the container.
The VM sits on its own little network:
$ docker run --rm --privileged --pid=host alpine nsenter -t 1 -n ip -br addr
eth0 UP 192.168.65.3/24
eth1 UP 192.168.64.2/24
A few consequences that confuse people:
- Container IPs (
172.17.0.x) are IPs inside the VM. You can ping them from a Linux host; from your Mac, they don’t exist. --network hostgives the container the VM’s network, not your Mac’s. On Linux, it’s how you skip port publishing. On a Mac it historically did nothing useful, and the newer opt-in host networking mode works by proxying ports to the Mac again.- To reach a service on your Mac from a container, use
host.docker.internal. That--host-gateway-ip 192.168.65.254flag ondockerdabove is exactly what it resolves to: the Mac, as seen from inside the VM.
4. Your images live in one giant file
Images, containers and volumes aren’t in some folder on your Mac. They’re inside the VM’s disk, which is a single sparse file:
$ ls -lh ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw
-rw-r--r-- 1 me staff 40G Docker.raw
$ du -h ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw
16G Docker.raw
40 GB apparent size, 16 GB actually used on disk. From inside the VM it’s just a block device:
/dev/vda1 40G 16G 22G 44% /var/lib
Same 16 GB. If your Mac’s “System Data” looks suspiciously chunky, this file is
a usual suspect, and docker system prune is how you shrink it, not deleting
random stuff in Finder.
5. amd64 images get emulated
The VM matches your CPU, so on Apple silicon it’s linux/arm64. Pull an image
that only ships linux/amd64 (still common for internal images and older
tools) and the VM has to emulate x86. With Rosetta disabled, which is how my
setup was, it does that through QEMU registered in binfmt_misc:
$ docker run --rm --platform linux/arm64 --privileged --pid=host alpine \
nsenter -t 1 -m ls /proc/sys/fs/binfmt_misc/
arm i386 mips64 ... riscv64 s390x x86_64
$ docker run --rm --platform linux/amd64 alpine uname -m
x86_64
It works, which is why nobody notices. Until they time it:
debian:bookworm-slim |
arm64 (native) | amd64 (QEMU) | slowdown |
|---|---|---|---|
sha256sum of 1 GB |
3.3 s | 8.5 s | 2.6x |
| bash loop, 2M iterations | 6.6 s | 74.6 s | 11.3x |
If someone on your team says “the tests take 3x longer on my machine”, check
the platform of the image before checking anything else. Ship multi-arch images
(docker buildx build --platform linux/amd64,linux/arm64), or at least turn on
the Rosetta option in Docker Desktop, so x86 binaries go through Apple’s far
faster translator instead of QEMU’s generic one.
“But I use OrbStack / Colima / Podman”
Same deal, different wrapper. OrbStack, Colima (via Lima), Rancher Desktop and
podman machine all boot a Linux VM; they just tune the VM, file sharing and
networking differently, which is why some of them are noticeably faster.
Apple’s own container tool goes the other way and boots a separate
lightweight VM per container. On Windows, Docker Desktop runs on WSL2,
which is… also a VM.
The only place docker run gives you a plain process on the host kernel is
Linux.
Conclusions
None of this means Docker on a Mac is bad. The VM is the only reasonable way to run Linux containers on a non-Linux kernel, and Docker Desktop hides it so well that most people never find out it’s there. But it’s there, and once you know it, the weird stuff stops being weird:
- slow
npm installin a bind mount: every file op crosses the VM boundary; - OOM kills on a 32 GB machine: the VM has 2.4 GB;
- can’t reach
172.17.0.2: that IP lives inside the VM; - tests 10x slower for one colleague: they’re running an amd64 image under emulation.
Next time somebody says “but it works in Docker on my laptop”, remember that their laptop is running a Linux server with 4 cores and 2.4 GB of RAM, and that’s what actually worked.