Tuning Docker Desktop Memory and CPU Limits

Containers die with exited with code 137, Postgres restarts in a loop with server process was terminated by signal 9: Killed, or a webpack build inside a container stalls at 92% — while on the host, the IDE freezes and kernel_task pegs the CPU. Both symptoms come from the same setting: the fixed amount of memory and CPU given to Docker Desktop's Linux VM. This page shows how to size it from measurements rather than guesses and how to keep that size consistent across the team, under choosing and tuning a local container runtime.

The defaults — half the host's memory on recent versions, 2 GiB on older installs, and every CPU core — are wrong in opposite directions for most development stacks, which is why the problem shows up so often on otherwise healthy laptops.

Diagnostic

Confirm that a kill came from memory pressure and compare the VM's size with what the stack uses:

#!/usr/bin/env bash
set -euo pipefail
for c in $(docker ps -aq); do
  docker inspect --format '{{.Name}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' "$c"
done | grep -E 'exit=137|oom=true' || echo "no OOM-killed containers"
docker info --format 'VM memory: {{.MemTotal}} bytes, CPUs: {{.NCPU}}'
docker stats --no-stream --format 'table {{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}'

Expected bad output:

/shop-db-1 exit=137 oom=true
/shop-search-1 exit=137 oom=false
VM memory: 2079997952 bytes, CPUs: 10
NAME            MEM USAGE / LIMIT     MEM %
shop-api-1      612MiB / 1.937GiB     30.87%
shop-web-1      498MiB / 1.937GiB     25.11%
shop-worker-1   402MiB / 1.937GiB     20.27%

The VM has about 2 GiB, the three survivors already use 1.5 GiB of it, and the database was the kernel's chosen victim. oom=false with exit 137 on the search container means it was killed by something else — usually a service-level mem_limit or a manual docker kill — so check its own limit before raising the VM size.

Root cause

Docker Desktop runs containers in one Linux VM whose memory is reserved from the host at start. Inside the VM there is no swap to speak of, so when the containers together exceed the VM's memory, the Linux out-of-memory killer picks the process with the highest badness score — usually the largest — and sends SIGKILL, which Docker reports as exit code 137. The CPU setting fails the other way: giving the VM every core lets a parallel build or a runaway file watcher starve the host, and on macOS the thermal response throttles everything, including the build. Neither setting is stored in the repository, so each developer's VM ends up sized by whatever they last clicked, and the team debugs identical Compose files behaving differently on every laptop.

Resolution

1. Measure steady state with the full stack running. Bring up everything, exercise the main flows for a minute, then sum the usage:

#!/usr/bin/env bash
set -euo pipefail
docker compose up -d
sleep 90
docker stats --no-stream --format '{{.MemUsage}}' | awk '{u=$1; if (u ~ /GiB/) {sub(/GiB/,"",u); t+=u*1024} else {sub(/MiB/,"",u); t+=u}} END {printf "steady state %.0f MiB\n", t}'

2. Compute the VM size. Steady state × 1.5 for spikes, plus 2 GiB for BuildKit during image builds, capped at half of physical memory. For a stack using 2.6 GiB on a 16 GiB laptop: 2.6 × 1.5 + 2 ≈ 5.9, so 6 GiB. For CPUs, leave at least two cores for the host: 8 of 10 on an M-series Pro, 6 of 8 on an 8-core laptop.

3. Apply the setting. Use Settings → Resources in the GUI, or write the values into Docker Desktop's settings file and restart it so the change is scriptable:

#!/usr/bin/env bash
set -euo pipefail
f="$HOME/Library/Group Containers/group.com.docker/settings-store.json"
[ -f "$f" ] || f="$HOME/Library/Group Containers/group.com.docker/settings.json"
tmp="$(mktemp)"
jq '.MemoryMiB = 6144 | .Cpus = 8 | .SwapMiB = 1024' "$f" > "$tmp" && mv "$tmp" "$f"
osascript -e 'quit app "Docker"'
open -a Docker
until docker info >/dev/null 2>&1; do sleep 2; done
docker info --format 'VM memory {{.MemTotal}} CPUs {{.NCPU}}'

Recent Docker Desktop versions use settings-store.json with the keys shown; older versions use settings.json with memoryMiB and cpus. Check the file before scripting against it.

4. Add per-service limits so a runaway service is killed alone rather than taking the database with it, and cap JVM heaps below their container limit:

services:
  db:
    image: postgres:16.4
    deploy:
      resources:
        limits:
          memory: 1536m
  search:
    image: opensearchproject/opensearch:2.15.0
    environment:
      OPENSEARCH_JAVA_OPTS: -Xms512m -Xmx512m
    deploy:
      resources:
        limits:
          memory: 1g
          cpus: "2"

Expected output

$ docker info --format 'VM memory {{.MemTotal}} CPUs {{.NCPU}}'
VM memory 6208172032 CPUs 8
$ docker compose ps --format '{{.Service}} {{.State}} {{.Health}}'
api running healthy
db running healthy
search running healthy
web running
worker running
$ docker inspect --format '{{.State.OOMKilled}}' shop-db-1
false

Every service stays up through a full build and test run, and the host keeps two cores and about 10 GiB free for the IDE and browser.

Prevention

1. Check the VM size in make doctor. Compare docker info against the team baseline and print the fix:

#!/usr/bin/env bash
set -euo pipefail
need_mib=6144
have_mib=$(( $(docker info --format '{{.MemTotal}}') / 1024 / 1024 ))
if [ "$have_mib" -lt $(( need_mib - 256 )) ]; then
  echo "Docker VM has ${have_mib} MiB, stack needs ${need_mib} MiB: Settings > Resources > Memory"; exit 1
fi

2. Re-measure after adding a service. A new search engine or message broker can add a gigabyte; update the baseline in the same pull request that adds the service.

3. Keep limits in Compose, not in personal settings, so every developer and CI job gets the same per-service ceilings.

Platform caveats

WSL2: Docker Desktop's resource sliders are disabled with the WSL2 backend. Set limits in %UserProfile%\.wslconfig with [wsl2], memory=6GB and processors=8, then run wsl --shutdown. Without a limit, WSL2 can take up to half of RAM and hold file cache long after containers stop.

macOS (Docker Desktop): memory is reserved lazily but rarely returned to macOS. After a heavy build, Activity Monitor may show the VM using its full allocation even when containers are idle; restarting Docker Desktop returns it.

Apple Silicon (ARM64): amd64 images under Rosetta use more memory than native builds of the same service. Prefer arm64 images for the largest services before raising the VM size.

Rollback

Restore the previous values in the settings file or reset to defaults with Troubleshoot → Reset to factory defaults (which also deletes images and volumes — dump data first). Per-service limits are removed by reverting the Compose change.

#!/usr/bin/env bash
set -euo pipefail
git restore compose.yaml
docker compose up -d --force-recreate

Frequently Asked Questions

Related

• Run only part of the stack to save memory
• Diagnose containers that exit right after start
• Free the disk space the VM has accumulated