Wait for Docker Containers and Capture Their Exit Codes

You will finish with a repeatable way to wait for one or more Docker containers to stop and record the exit codes they returned. This guide uses Docker CLI 29.8.1 from the docker-ce-cli package, version 5:29.8.1-1~ubuntu.24.04~noble. Allow about ten minutes if the containers already exist, or a little longer if you need to build a small test case.

You need a shell, access to the Docker daemon, and the names or IDs of the containers you want to observe. The ordinary docker wait command is not an elevated operation. Use sudo only if your Docker installation requires it, and remember that access to the Docker socket is itself a privileged capability.

1. Check the installed command

The installed command is an alias for docker container wait. It accepts a container name or ID, followed by one or more additional containers:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker wait --help
Usage:  docker wait CONTAINER [CONTAINER...]

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

There are no wait-specific flags in this interface. The container argument is required, and the command blocks while a target is still running. Checkpoint: if your output shows a different usage line, read that installed help before copying the examples below.

2. Wait for one named container

Give Docker the name or ID of a container. This command returns one line containing the container's exit code after the container has stopped:

$ docker wait IMAGE_PROCESSOR
0

Replace IMAGE_PROCESSOR with a real container name or ID. A zero means that the container's main process exited successfully. A non-zero number is the exit status reported by that process, so it is meaningful application data rather than proof that docker wait itself malfunctioned.

The command does not stop the container, send a signal, restart it or remove it. If the target is already stopped, it can return immediately with the recorded exit code. If it is running, keep the terminal open: the apparent pause is the requested behaviour.

3. Preserve the exit code in a shell script

Capture the output and the command status separately. The command status tells you whether the Docker CLI completed the wait request; the printed value tells you how the container's main process ended:

container_name='IMAGE_PROCESSOR'
exit_code=$(docker wait "$container_name")
docker_status=$?

if [ "$docker_status" -ne 0 ]; then
    printf 'docker wait failed with status %s\n' "$docker_status" >&2
    exit "$docker_status"
fi

printf 'container %s exited with code %s\n' "$container_name" "$exit_code"
if [ "$exit_code" -ne 0 ]; then
    exit "$exit_code"
fi

Quote the name even when your current names contain no spaces. It keeps the script safe if the value later comes from an environment variable or another command. The assignment uses command substitution, so normal output from docker wait becomes the value of exit_code; the next line immediately saves the CLI status before another command can replace it.

Checkpoint: test the failure path with a container whose workload is expected to fail, then confirm that the script reports the container code. Do not treat a successful Docker CLI status alone as a successful job.

4. Wait on several containers

The syntax permits several container arguments:

$ docker wait IMAGE_PROCESSOR IMAGE_EXPORTER
0
2

Docker prints an exit code for each requested container. Keep the order visible in your own logs, because a bare list of numbers is easy to misread later. For a fixed pair, label the results explicitly:

processor_code=$(docker wait IMAGE_PROCESSOR)
processor_status=$?
exporter_code=$(docker wait IMAGE_EXPORTER)
exporter_status=$?

if [ "$processor_status" -ne 0 ] || [ "$exporter_status" -ne 0 ]; then
    printf 'wait request failed: processor=%s exporter=%s\n' \
        "$processor_status" "$exporter_status" >&2
    exit 1
fi

printf 'processor=%s exporter=%s\n' "$processor_code" "$exporter_code"
[ "$processor_code" -eq 0 ] && [ "$exporter_code" -eq 0 ]

This waits for the first named container before asking for the second. If you need to observe several long-running containers concurrently, start one waiter per container in a controlled supervisor or background job and record each name with its result. Do not assume that listing several arguments makes the shell run independent waits in parallel.

5. Handle names, IDs and missing containers

A name is usually clearer in an operational script, while an ID or unambiguous ID prefix is useful for one-off diagnosis. Resolve the target before waiting when a script discovers it dynamically:

container_name='IMAGE_PROCESSOR'
if ! docker container inspect "$container_name" >/dev/null 2>&1; then
    printf 'container not found: %s\n' "$container_name" >&2
    exit 2
fi

exit_code=$(docker wait "$container_name")
status=$?
printf 'docker status=%s container exit=%s\n' "$status" "$exit_code"

Inspection does not change the container. It only turns a misspelled or removed target into an earlier, clearer failure. If another process removes the container between inspection and wait, handle the wait failure as a race rather than retrying blindly against an unknown replacement.

6. Avoid destructive shortcuts

docker wait is read-only with respect to container lifecycle, but the surrounding commands may not be. Do not add docker stop, docker kill or docker rm just to make a wait finish. Those commands can disrupt work or remove the evidence needed to diagnose a failed job.

If you created a disposable test container and want to remove it after recording its result, verify the name first and then remove only that explicit target:

$ docker wait docker-wait-test
7
$ docker rm docker-wait-test
docker-wait-test

Removal is irreversible for the container's writable layer and local metadata. It does not remove the image, but it can discard logs and filesystem changes held only by that container. There is no undo command for docker rm, so preserve any required logs before running it.