Rebuild a service with Docker Compose

Rebuild the image when image-baked code or the Dockerfile changes, then use docker compose up to replace the service container. A restart only stops and starts the existing container; it does not adopt a rebuilt image or changed container environment.

Choose the operation

# Build the web image, then apply it.
docker compose build web
docker compose up -d web

# Or build and apply in one operation.
docker compose up -d --build web

# Apply changed service configuration.
docker compose up -d

# Replace web even when Compose detects no change.
docker compose up -d --force-recreate web

build leaves running containers alone. up --build invokes a build before starting services; the builder can reuse cache, and Compose decides whether the resulting image or configuration requires replacement. --force-recreate forces a new container but does not itself promise a fresh build or download.

To rebuild without instruction-cache reuse and check for newer base-image references:

docker compose build --no-cache --pull web
docker compose up -d web

These flags do not clear every package-manager cache or change a pinned image digest. Use them to investigate a specific cache issue, rather than making every build unnecessarily expensive.

Keep state outside the replacement

Replacement discards the old container's writable layer. Named volumes and existing bind-mounted data normally remain attached, subject to the service configuration. Avoid down -v unless volume deletion is intended. Changed mount names or paths can attach different storage, so verify the actual mounts before and after.

Code mounted from the host is a separate case: the file change may already be visible without rebuilding, but the application may still need a reload or restart. This does not make restart a substitute for updating image-baked code.

Verify before cleaning up

docker compose ps web
docker compose logs --tail 100 web
docker compose images web

Send a representative request and confirm the running version. If Guance APM is already configured, compare collected requests in trace details and correlate errors with a version field in logs. A changing chart alone does not establish the cause.

docker image prune removes eligible dangling images; it is not a full build-cache cleanup. Review retention needs and keep the image required for rollback before pruning.

FAQ

Why does build skip a service? An image-only service has no local build definition. Pull the required image and run up. A service can declare both build and image, so the mere presence of image does not prevent building; pull policy also matters.

Can I build all services? docker compose build without service names builds services with build definitions.

Why are builds slow? Check which steps lose cache. Copy dependency manifests before frequently changing source files when the dependency installation supports that arrangement. Also inspect the build context and external dependency downloads.

See Compose build reference, Compose up reference, Compose restart reference.