2026/10/15

Share

on:

Docker on macOS is a Linux VM in a trench coat

share

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

What actually runs when you type docker run on a MacProcess names, paths and addresses taken from Docker Desktop 28.5.1 on an M1 Pro.
macOS · XNU kernel · darwin/arm64
  • dockerthe CLI you type into
  • com.docker.backendsocket proxy, port forwarder, network stack
  • com.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
Linux VM · 6.10.14-linuxkit · linux/arm64 · 4 vCPU · 2.4 GB
  • dockerdthe actual Docker daemon
  • containerdcontainer lifecycle
  • runcnamespaces + cgroups
nginx
postgres
your app

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:

Same workload, three places to put the filesMedian of 3 runs, debian:bookworm-slim, arm64. Log scale: every gridline is 10x.
bind mount (virtiofs)named volumecontainer fs
untar 20k Ă— 1 KB files106x slower on bind
14.6 s
138 ms
215 ms
rm -rf those 20k files45x slower on bind
7.6 s
169 ms
186 ms
stat 20k files51x slower on bind
1.0 s
20 ms
24 ms
write 512 MB + fsync
452 ms
503 ms
381 ms
10 ms100 ms1.0 s10.0 s
Raw runs
whereuntarstatwriterm
bind14638 / 13731 / 14578991 / 1029 / 1063493 / 452 / 3917636 / 7615 / 7400
volume218 / 137 / 13821 / 19 / 20503 / 583 / 468169 / 175 / 164
container fs296 / 214 / 21524 / 23 / 24370 / 405 / 381186 / 199 / 185
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/target on 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 host gives 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.254 flag on dockerd above 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 install in 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.