Wait for Docker Containers and Capture Their Exit Codes

You will finish with a small, repeatable Docker workflow that starts a background container, waits for it to stop, and records the exit status that Docker reports. The examples use Docker CE CLI 29.8.1, installed from package version 5:29.8.1-1~ubuntu.24.04~noble. Allow about ten minutes if Docker is already running, or longer if you need to diagnose the daemon first.

You need the Docker CLI, access to a Docker daemon, and permission to run containers. The command itself normally needs no sudo when your account already has Docker access. Adding sudo changes which Docker configuration and daemon access are used, so do not add it as a reflex.

1. Check the installed command

Confirm the version and the exact syntax before putting the command into a script:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker container wait --help
Usage:  docker container wait CONTAINER [CONTAINER...]

Block until one or more containers stop, then print their exit codes

Aliases:
  docker container wait, docker wait

docker container wait and its shorter alias docker wait have the same purpose. A container argument is required. The command does not start, stop or restart a container by itself; it waits for a container that is already running or has stopped.

2. Start a disposable test container

Run a short-lived container in the background. This example uses the small Fedora image from the installed manual and gives the container an explicit name so the later command is readable:

$ docker run --detach --name wait-demo fedora sleep 3
<container-id>

The long hexadecimal value is the container ID. With --name wait-demo, you can use the name instead. The sleep 3 process is the container's main process, so the container should stop after roughly three seconds.

This command downloads fedora if the image is not already present and creates a container. It is safe to remove the test container after the exercise, but do not use the removal commands below for a container that owns data or serves a real workload.

3. Wait for the container to stop

Run the wait command before the three seconds have elapsed if you want to see it block:

$ docker container wait wait-demo
0

The command stays attached until wait-demo stops, then prints the main process exit code. In this example sleep completed normally, so the result is 0. The command's own exit status also indicates whether Docker could complete the wait:

$ status=$?
$ printf 'reported container code: %s\n' "$status"
reported container code: 0

Do not confuse the printed value with a shell error from the Docker CLI. The printed number is the stopped container's exit code. The shell status is useful when writing a script, but capture it immediately because another command will replace $?.

4. Wait for a failing container

To see a non-zero application result without changing a host service, create another disposable container whose main process exits with status 42:

$ docker run --detach --name wait-failure fedora sh -c 'exit 42'
<container-id>
$ docker container wait wait-failure
42

The number comes from the process running as PID 1 in the container. This is useful for a wrapper script that must wait for a job and then decide whether to continue:

$ result=$(docker container wait wait-failure)
$ case "$result" in
    0) echo 'container completed successfully' ;;
    *) printf 'container failed with exit code %s\n' "$result" >&2; exit "$result" ;;
  esac
container failed with exit code 42

Keep the container name or ID stable while the wait is in progress. If another process removes the container before Docker reports its result, the wait cannot complete normally.

5. Coordinate a deliberate stop

A wait is also useful when another terminal or process owns the decision to stop a container. Start a long sleep in one terminal:

$ docker run --detach --name wait-stop-demo fedora sleep 300
<container-id>
$ docker container wait wait-stop-demo
0

While the wait is blocked, stop the container from a second terminal:

$ docker stop wait-stop-demo
wait-stop-demo

Docker sends the container its normal stop signal and waits for the stop operation to finish. The waiting command then prints the exit code reported by the stopped container. Stopping a real service is service-disrupting, so use a maintenance window and confirm the container name before running docker stop.

6. Handle names, IDs and common failures

You can pass a full or recognisable container ID instead of a name. List the relevant containers without changing them:

$ docker ps --all --filter name=wait-demo --format 'table {{.Names}}\t{{.Status}}\t{{.ID}}'
NAMES       STATUS                     CONTAINER ID
wait-demo   Exited (0) 5 seconds ago   <container-id>

The displayed ID is shortened by the format string. Copy the exact name from the first column when possible. If Docker says that a container cannot be found, check that you are using the same Docker context and account that created it:

$ docker context show
default
$ docker ps --all --filter name=wait-demo

If the command appears to hang, that is normally its contract: the target container has not stopped. Check its state from another terminal with docker ps. If the container is expected to run indefinitely, waiting is the wrong operation unless another process will stop it.

7. Remove only the disposable examples

After checking the output, remove the test containers. This changes Docker state and is irreversible for the container's writable layer, so verify the names first:

$ docker ps --all --filter name=wait-demo --filter name=wait-failure --filter name=wait-stop-demo --format '{{.Names}}'
wait-demo
wait-failure
wait-stop-demo
$ docker rm wait-demo wait-failure wait-stop-demo
wait-demo
wait-failure
wait-stop-demo

Removing a container does not remove the image named fedora. It also does not recover files written only into a removed container's writable layer. Keep a container instead of removing it if you still need its logs or filesystem for investigation, and use docker logs NAME before cleanup when output matters.