Docker on macOS / Windows cheatsheet.

Why it’s different

Docker runs Linux. On macOS / Windows, you need a Linux VM. Docker Desktop bundles one. Alternatives:

  • Docker Desktop: official, paid for some companies (>250 emp).
  • OrbStack (macOS): much faster file sharing, low overhead.
  • Rancher Desktop: open source.
  • Colima: minimal CLI alternative on macOS.
  • Lima: barebones Linux VM.
  • Podman Desktop: docker-compatible alternative.

File sharing performance

Macs/Windows bind mounts go through a VM filesystem bridge:

# Slow:
volumes:
  - .:/app

# Faster with consistency flag:
volumes:
  - .:/app:cached       # host-authoritative
  - .:/app:delegated    # container-authoritative

:cached / :delegated allow eventual consistency for speed.

brew install --cask orbstack
  • Native file sharing (no VM bridge slowness).
  • Native ARM64.
  • Faster startup.
  • Drop-in docker CLI replacement.

Colima

brew install colima
colima start --cpu 4 --memory 8 --disk 60
docker context use colima
docker ps                    # works

Just a VM + Docker. Minimal, fast.

Rosetta on Apple Silicon

For x86 images on M-series Macs, Docker Desktop emulates via QEMU (slow) or Rosetta (faster).

Enable in Docker Desktop settings → “Use Rosetta for x86_64/amd64 emulation”.

Or build native ARM images:

docker buildx build --platform linux/arm64 -t myapp:arm .

Networking

localhost from container reaches the VM, not your host. To reach host:

host.docker.internal

Works on Docker Desktop. On Linux, add --add-host=host.docker.internal:host-gateway.

Port forwarding

-p 8080:80 forwards from your host (Mac/Win) through VM to container. Works seamlessly.

File watchers

inotify / fsevents don’t propagate across the VM well. Hot-reload may be slow.

Workarounds:

  • Use polling: chokidar --polling, webpack --poll=1000.
  • Use a faster file-sharing tool (OrbStack handles this).

Volume drivers (named volumes are fast)

volumes:
  - data:/var/lib/data           # named volume, fast
  # vs
  - ./data:/var/lib/data         # bind mount, slower on Mac/Win

For databases: always use named volumes on Mac/Windows. Bind mounts to DB data dirs cause performance issues.

Resource allocation

Docker Desktop: Preferences → Resources.

  • CPUs: 4-8 typical.
  • Memory: 8-16GB (more = better for heavy stacks).
  • Swap: 1GB.
  • Disk image size: 60GB+.

VirtioFS (Docker Desktop)

Faster than gRPC FUSE for shared files. Enable in Docker Desktop settings.

WSL2 (Windows)

Docker Desktop integrates with WSL2:

docker ps         # works from PowerShell
wsl
docker ps         # also works in WSL

Run containers + dev environment in WSL2 for performance.

Performance tips

  1. Use OrbStack or Colima on macOS.
  2. Avoid bind-mounting big trees (node_modules, .next).
  3. Use anonymous volumes to hide them: - /app/node_modules.
  4. Named volumes for DB data.
  5. Adequate CPU / RAM in VM settings.

Apple Silicon image tips

Most images now have arm64 variants. Check:

docker manifest inspect nginx | jq '.manifests[].platform'

For x86-only images: build a local arm64 version or accept emulation.

Cross-arch building

docker buildx create --use --name multi
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:v1 --push .

Filesharing alternatives: mutagen

brew install mutagen-io/mutagen/mutagen

Syncs files at native speed instead of VM bridge. Used by some teams for big repos.

docker context

Switch between local and remote Docker engines:

docker context create remote --docker host=ssh://user@server
docker context use remote
docker ps        # runs on remote
docker context use default

Avoiding Docker Desktop on macOS

brew install colima docker docker-compose
colima start
docker ps        # uses colima

Lightweight, no Desktop UI.

Common mistakes

  • Bind-mounting node_modules → super slow.
  • Running too many containers → starves Mac.
  • x86-only image on M-series without buildx → painful.
  • Treating host = container — networking differs.
  • Forgetting to allocate enough RAM in Docker Desktop.

Read this next

If you want my OrbStack + Colima setup recipes, they’re at rajpoot.dev .

Building something AI-, backend-, or data-heavy and want a second pair of eyes? I do consulting and freelance work — see my projects and ways to reach me at rajpoot.dev .