Docker Compose restart Ignores New Environment Variables: Recreate the Container

Why restart keeps the old value#

Compose resolves variables and writes the resulting environment into the container configuration when the container is created. docker compose restart stops and starts that same container; it does not apply changes from compose.yaml or the files used for interpolation.

There are two checks worth keeping separate:

The distinction matters because a value can be correct in the newly rendered model while the old container still has the previous value. The Docker Compose variable interpolation guide covers the separate precedence rules for .env, --env-file, shell variables, and environment:.

Render and inspect before recreating#

From the directory that contains the intended Compose project, render the model first:

1
docker compose config --environment
2
docker compose config

Do not paste the full rendered output into a public issue if it contains passwords or tokens. For a service named web, inspect the value stored in its current container:

1
docker compose ps web
2
docker inspect "$(docker compose ps -q web)" \
3
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
4
  | grep '^APP_MODE='

If the rendered value and the inspected value differ, the container is stale. If they match but the application still behaves differently, inspect the application’s own configuration loading and the distinction between build-time and runtime variables.

Recreate only the service that changed#

For a runtime environment change, recreate the service without rebuilding its image:

1
docker compose up -d --no-deps --force-recreate web

--force-recreate makes the lifecycle explicit, while --no-deps avoids restarting dependencies that did not change. If the Compose file’s configuration changed and you omit --force-recreate, docker compose up -d web can still detect the change and recreate the service. The explicit flag is useful in a deployment script when the update must not depend on change detection.

Named volumes are preserved during ordinary recreation, but data written only to the old container’s writable layer is not a volume backup. Check the service’s volume configuration before removing anything, especially when changing database credentials or storage paths.

Rebuild only when the image also changed#

An environment change is not automatically an image change. If you edited the Dockerfile or the image’s build arguments, rebuild before recreating:

1
docker compose build web
2
docker compose up -d --no-deps web

If the value is used by a frontend build, changing a runtime .env file after the image was built may be too late. Re-run the image build with the intended build-time variables, then verify the generated assets. A container can have the new runtime environment and still serve JavaScript that was compiled with the old value.

Verify the new container at the application boundary#

After recreation, check both Docker and the application:

1
docker compose ps web
2
docker compose logs --tail=100 web
3
docker inspect "$(docker compose ps -q web)" \
4
  --format '{{range .Config.Env}}{{println .}}{{end}}' \
5
  | grep '^APP_MODE='

Then call a health endpoint or exercise the code path that consumes the variable. Do not print secrets as proof; use a safe mode name, a feature flag, or a redacted diagnostic endpoint. If the value is a secret, consider a Docker secret or the hosting platform’s secret store instead of adding it to logs or a rendered configuration artifact.

The operational rule is: restart reuses a container, while up can create a new one from the current model. Use the smallest targeted recreation that matches the change and verify the value from the new container, not only from the file on disk.

FAQ#