How to Update a Running Docker Compose Container (Without Downtime Surprises)
⏱️ 2 min read
Updating a compose service is conceptually three steps: pull the new image, recreate the container from it, done. The surprises come from volumes, env vars, and doing it on the wrong service.
The safe sequence
1. Pull only what changed: docker compose pull web — pulling all services when one changed wastes time and can surprise you with upgrades you didn't mean to take (pinned tags drift too).
2. Recreate: docker compose up -d web. Compose detects the new image hash and recreates only that container, leaving dependencies alone unless --force-recreate. Add --build when the image is local, not from a registry.
3. Verify before you leave: docker compose ps and the logs (docker compose logs web --tail 50). Healthchecks in the compose file make this a no-thought step — depends_on: condition: service_healthy also prevents dependents from starting against a broken service.
The three classic bites
Env var changes ignored: editing .env then up -d DOES recreate on env change — but only if the variable is referenced in the compose file. Silent mismatch between .env names and compose references is the usual culprit.
Data loss scare: recreating a container does not touch named volumes or bind mounts. What vanishes is data written inside the container's writable layer — which is exactly why databases in compose need a named volume on day one, not after the first scare.
Old images piling up: every update orphans the previous image. docker image prune -f after the rollout keeps the disk from creeping full — the #1 cause of "No space left on device" on small servers.
Going further
When you outgrow compose's recreate model (real zero-downtime, multiple app replicas), the same image workflow moves to a small Kubernetes cluster or a rolling-deploy platform. Running a practice box first — DOKS on DigitalOcean or Vultr's managed Kubernetes — makes the jump a weekend project instead of a gamble.