States of a Docker Container

Last updated: March 19, 2024

Reviewed by: Michal Aibin

1. Overview

A Docker container is an instance of a Docker image that runs some process inside it. As the state of this process changes, the behavior of the container is also affected. Thus, a container can be found in different states throughout its lifecycle.

In this tutorial, we’ll learn about all the possible states of a Docker container.

Let’s first look into how to find the state of a Docker container, and then we’ll go through different stages of the container.

2. Find the Current State of a Docker Container

Before we dive deep into different states of a Docker container, let’s first look into how to find the state of any Docker container.

By default, the docker ps command displays the current state of all the Docker containers:

$ docker ps -a
CONTAINER ID   IMAGE      COMMAND       CREATED              STATUS                          PORTS     NAMES
8f0b524f2d32   centos:7   "/bin/bash"   46 seconds ago       Created                                   strange_beaver
e6d798254d45   centos:7   "/bin/bash"   About a minute ago   Exited (0) About a minute ago             wizardly_cohen

The output displays all the containers present on the machine with their STATUS (fifth column) and a bunch of other details.

We can also use the docker inspect command to get the status of a single container:

$ docker inspect -f '{{.State.Status}}' mycontainer
running

Here, mycontainer is the container name for which we wish to find the current state. We can also replace it with the Docker container id.

3. Possible States of a Docker Container

At any particular instance, a Docker container can be found in 6 possible states. Let’s now deep dive into each of these states:

3.1. Created

Docker assigns the created state to the containers that were never started ever since they were created. Hence, no CPU or memory is used by the containers in this state.

The Docker containers created using the docker create command shows the status as created:

$ docker create --name mycontainer httpd
dd109e4be16219f1a6b9fc1cbfb050c1ae035d6a2c301ea0e93eb7d5252b8d2e
$ docker inspect -f '{{.State.Status}}' mycontainer
created

Here, we have created a Docker container, mycontainer, using the official Docker image of httpd. Since we have used the docker create command to launch the container, so the status is shown as created. 

Such containers are useful when we need to keep ourselves prepared for some big tasks. In such situations, we create the container so that it’s ready to go when we start it.

3.2. Running

When we start a container having created a state using the docker start command, it attains the running state.

This state signifies that the processes are running in the isolated environment inside the container.

$ docker create --name mycontainer httpd
8d60cb560afc1397d6732672b2b4af16a08bf6289a5a0b6b5125c5635e8ee749
$ docker inspect -f '{{.State.Status}}' mycontainer
created
$ docker start mycontainer
mycontainer
$ docker inspect -f '{{.State.Status}}' mycontainer
running

In the above example, we first created a Docker container using the official httpd Docker image. Then, the status of the container was created. When we start the mycontainer, the httpd server process and all other relevant processes begin to run. Hence the status of the same container has now changed to running.

The container ran using the docker run command also attained the same status:

$ docker run -itd --name mycontainer httpd
685efd4c1c4a658fd8a0d6ca66ee3cf88ab75a127b9b439026e91211d09712c7
$ docker inspect -f '{{.State.Status}}' mycontainer
running

In this state, there is no compromise in the CPU and memory consumption by the container.

3.3. Restarting

Simply put, this state denotes that the container is under the process of restart. 

Docker supports four types of restart policies, namely – no, on-failure, always, unless-stopped. Restart policy decides the behavior of the container when it exit.

By default, the restart policy is set to no, which means that the container will not be started automatically after it exits.

Let’s update the restart policy to always and verify the Docker container state using the below example:

$ docker run -itd --restart=always --name mycontainer centos:7 sleep 5
f7d0e8becdac1ebf7aae25be2d02409f0f211fcc191aea000041d158f89be6f6

The above command will run the mycontainer and execute the sleep 5 command and exit. But since we have updated the restart policy for this container, it will automatically restart the container after it exits.

After 5 seconds, the state of the container will be restarting:

$ docker inspect -f '{{.State.Status}}' mycontainer
restarting

3.4. Exited

This state is achieved when the process inside the container terminates. In this state, no CPU and memory are consumed by the container.

There could be several reasons why a running container would exit. Let’s look into a few of them:

  • The process inside the container was completed, and so it exited.
  • The process inside the container encountered an exception while running.
  • A container is intentionally stopped using the docker stop command.
  • No interactive terminal was set to a container running bash.
$ docker run -itd --name mycontainer centos:7 sleep 10
596a10ddb635b83ad6bb9daffb12c1e2f230280fe26be18559c53c1dca6c755f

Here, we have started a centos container, mycontainer, and passed the command sleep 10. This will exit the container after 10 seconds of sleep. We can verify the same by running the following command after 10 seconds:

$ docker inspect -f '{{.State.Status}}' mycontainer
exited

A container in the exited state cannot be accessed using the docker exec command. However, we can start the container using the docker start or docker restart and then access it.

$ docker start mycontainer

3.5. Paused

Paused is the state of a Docker container that suspends all the processes for an indefinite time. 

A Docker container can be paused using the docker pause command.

$ docker run -itd --name mycontainer centos:7 sleep 1000
1a44702cea17eec42195b057588cf72825174db311a35374e250d3d1da9d70c5

In the above example, we started a Docker container using the centos Docker image and ran the command sleep 1000. This will exit the container after 1000 seconds of sleep.

Now let’s pause this container after a few seconds, say 100 seconds:

$ docker pause mycontainer
mycontainer
$ docker inspect -f '{{.State.Status}}' mycontainer
paused

A paused container consumes the same memory used while running the container, but the CPU is released completely. Let’s verify this using the docker stat command:

$ docker stats --no-stream
CONTAINER ID   NAME          CPU %     MEM USAGE / LIMIT    MEM %     NET I/O       BLOCK I/O   PIDS
1a44702cea17   mycontainer   0.00%     1.09MiB / 7.281GiB   0.01%     1.37kB / 0B   0B / 0B     1

Notice that the CPU is 0%, but the memory usage is not zero.

We can use the docker unpause command to resume the container:

$ docker unpause mycontainer
mycontainer

On unpausing the container, it will resume from the same point where we paused it. In our example above, we paused the container after 100 seconds of sleep. So when we unpause the container, it will resume its sleep from 100. Therefore, the container will stop after 900 seconds of sleep from this point. (total sleep was set to 1000).

Now the question is when to pause a Docker container? Consider a situation when a Docker container is performing some CPU-intensive task. At the same time, we wish to run another CPU-intensive container with high priority. Of course, we can run both containers simultaneously, but it will slow down the execution due to a lack of resources.

In such cases, we can pause one of the containers with low priority for some time and let the other container use the complete CPU. Once it’s done, we can unpause the execution of the first container.

3.6. Dead

The dead state of a Docker container means that the container is non-functioning. This state is achieved when we try to remove the container, but it cannot be removed because some resources are still in use by an external process. Hence, the container is moved to the dead state.

Containers in a dead state cannot be restarted. They can only be removed.

Since a container in a dead state is partially removed, so it does not consume any memory or CPU. 

4. Conclusion

In this tutorial, we went through different stages of a Docker container.

First, we looked into a couple of ways to find the state of a Docker container. Later, we learned the importance of each state and how to achieve those states using different Docker commands.

Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.