✦ For everyone, free.

Practical knowledge for real and everyday life

Home

19.2.2.5 Ps Runtime State

A focused guide to Ps Runtime State, connecting core concepts with practical Docker and container operations.

Runtime state refers to the current lifecycle condition of a Docker container at any given moment, as reported by docker ps. Every container exists in one of a defined set of states, and the STATUS column in docker ps output reflects that state along with additional context such as how long the container has been in that state or what exit code it produced.

The Container State Machine

A container moves through states in response to commands, process events, and policy triggers:

Created Running Paused Restarting Exited Dead

State Definitions

created

The container has been initialized with docker create but docker start has not been called. The container's filesystem and configuration are fully allocated, but the primary process has not been started. Resources (network namespace, cgroup entries) are provisioned.

docker ps -a -f "status=created"

From created, the container transitions to running when started:

docker start my-container
running

The container's primary process (PID 1 inside the container) is alive and executing. This is the active state. docker ps without flags shows only containers in this state.

STATUS example: Up 3 hours, Up 5 seconds, Up 4 days

Health check variants:

  • Up 3 hours (healthy)
  • Up 1 hour (unhealthy)
  • Up 10 seconds (health: starting)
paused

The container's processes have been frozen using the cgroup freezer subsystem via docker pause. The processes exist and their memory is intact, but they are not scheduled for CPU time. The container does not accept new connections and does not consume CPU.

docker pause my-container

STATUS example: Up 2 hours (Paused)

Resume with docker unpause my-container, which returns the container to running.

restarting

The container has exited and is being restarted by a restart policy (--restart on-failure, --restart always, etc.). The container cycles through this state repeatedly if it keeps crashing. Docker applies an exponential backoff between restart attempts.

STATUS example: Restarting (5) 2 seconds ago

The number in parentheses is the restart count. A high count indicates a crash loop.

To check what is causing repeated restarts:

docker logs my-container --tail 50
exited

The container's primary process has terminated. The container retains its filesystem, configuration, and logs but is no longer consuming CPU or memory. It remains visible with docker ps -a.

STATUS examples:

  • Exited (0) 10 minutes ago — successful completion
  • Exited (1) 2 hours ago — application error
  • Exited (137) 1 hour ago — killed (OOM or SIGKILL)
  • Exited (143) 3 hours ago — graceful stop (SIGTERM)

The exit code in parentheses is the return value of the container's primary process.

removing

A transient state during which the container is being deleted. This state is usually too brief to observe in normal operation. A container enters removing when docker rm is in progress.

dead

The container has entered an unrecoverable error state. This happens when Docker cannot properly remove a container (for example, due to a filesystem error or a partially completed removal that left inconsistent state). Dead containers must be force-removed:

docker rm -f dead-container

Viewing Runtime State

docker ps -a --format "table {{.Names}}\t{{.Status}}"

NAMES          STATUS
web-server     Up 3 hours (healthy)
database       Up 3 hours
cache          Up 1 hour
app-test       Exited (0) 55 minutes ago
app-failed     Exited (1) 23 hours ago
dev-session    Exited (130) 2 hours ago
unused-env     Created

Filtering by State

docker ps -a -f "status=running"
docker ps -a -f "status=exited"
docker ps -a -f "status=paused"
docker ps -a -f "status=restarting"
docker ps -a -f "status=created"
docker ps -a -f "status=dead"

Retrieving Exit Code Programmatically

docker inspect --format '{{.State.ExitCode}}' my-container

Other state fields available through inspect:

docker inspect --format '{{.State.Status}}' my-container        # "running", "exited", etc.
docker inspect --format '{{.State.StartedAt}}' my-container     # ISO 8601 timestamp
docker inspect --format '{{.State.FinishedAt}}' my-container    # ISO 8601 timestamp
docker inspect --format '{{.State.OOMKilled}}' my-container     # true if killed by OOM
docker inspect --format '{{.State.Paused}}' my-container        # true if paused
docker inspect --format '{{.State.Restarting}}' my-container    # true if restarting
docker inspect --format '{{.RestartCount}}' my-container        # number of restarts

Related content