DockerDevOps & Deployment

Why Docker Compose Restart Ignores Configuration Changes

Why restarting a Compose service keeps its old mounts and environment, how to confirm the mismatch, and when to use up or down instead.

Cargo ship carrying Linux containers while one container drifts away beneath the words Config Drift
Lead image Cargo ship carrying Linux containers while one container drifts away beneath the words Config Drift
On this page

Audio edition

0:00 / 3:27

Ready

docker compose restart is not a command for applying a changed Compose file. That distinction would have saved me an annoying debugging session.

I had changed a bind mount, restarted the service, and still saw the old files. Even stopping and starting the service did not help. The Compose file described the state I wanted, but the existing container still held the configuration with which it had been created.

Restart brings back the same container

Consider this small service in compose.yaml (the same issue applies if the file is named docker-compose.yml):

services:
  webapp:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./initial-content:/usr/share/nginx/html

Now change the bind mount’s source directory:

services:
  webapp:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./new-content:/usr/share/nginx/html

Running this command restarts the container, but it does not create a container from the revised service definition:

docker compose restart webapp

The same lifecycle boundary applies to a stop followed by a start:

docker compose stop webapp
docker compose start webapp

stop preserves the container, and start starts that existing container. Neither operation changes its mounts, port mappings, or environment.

Inspect the container, not just the file

When the Compose file and the running service appear to disagree, inspect the container that Compose is managing:

docker inspect "$(docker compose ps -q webapp)"

In my case, the Mounts section still pointed to the original source:

"Mounts": [
  {
    "Type": "bind",
    "Source": "/path/to/project/initial-content",
    "Destination": "/usr/share/nginx/html"
  }
]

That output resolved the apparent contradiction. The file contained the new configuration; the container still had the old one.

Use up to apply the change

Docker’s restart documentation explicitly says that changes to compose.yml are not reflected by a restart. docker compose up is the operation that creates or reconciles services. When a service’s configuration or image has changed, Compose stops and recreates that service’s container while preserving mounted volumes.

For the changed bind mount, the correction is:

docker compose up -d webapp

Limiting the command to webapp makes the intended scope clear. After Compose recreates it, docker inspect should show ./new-content resolved to its absolute host path.

If you need Compose to recreate the service even when it does not detect a configuration or image change, add --force-recreate:

docker compose up -d --force-recreate webapp

That flag is useful for an explicit reset, but it is not required for an ordinary detected configuration change.

Reserve down for a project-wide reset

This also works:

docker compose down
docker compose up -d

It is broader than the original problem. down removes the project’s service containers and networks before up creates them again, so it can interrupt services that did not need to change.

By default, down does not remove named or anonymous volumes. Anonymous volumes are not automatically mounted by the next up, though, so they should not be treated as durable storage. Adding --volumes removes Compose-declared named volumes and attached anonymous volumes; external volumes are never removed. A configuration refresh is not a reason to risk persistent application data with that flag.

The practical boundary is:

  • Use restart when the container definition has not changed and you only need to restart its process.
  • Use up -d when the Compose configuration or image changed.
  • Use down followed by up -d when you deliberately want to recreate the whole Compose project and have accounted for the interruption.

Once I treated the running container as a created object rather than a live view of the YAML file, the stale mount stopped being mysterious.

Continue reading

Complete index →