Read Docker Container State Quickly with docker ps

In about five minutes, you can use docker ps to answer the routine questions that matter on a Docker host: what is running, what stopped, which container owns a name, and which IDs can be passed to another command. The examples here were checked with Docker 29.8.1 from the docker-ce-cli package.

You need a working Docker CLI and access to a Docker daemon. Most installations let your normal user query the daemon. If yours does not, prefix a read-only command with sudo, for example sudo docker ps. That changes access, not the meaning of the command. Do not add sudo automatically: Docker access is privileged on many systems, so granting a user membership of the docker group is itself an administrative security decision.

1. List the containers that are running

Run the command without options:

docker ps

The default table normally includes the container ID, image, command, creation time, status, ports and name. It lists running containers only. A quiet or healthy-looking result can therefore mean either that no containers are running or that stopped containers were not requested. Check the command itself before drawing conclusions.

On a host with containers, expect rows shaped like this. Values will differ on your machine:

CONTAINER ID   IMAGE          COMMAND        CREATED        STATUS       PORTS     NAMES
64af3171d579   postgres:16    "docker-entrypoint"   2 minutes ago   Up 2 minutes             example-db

2. Include stopped containers

Use --all, or its short form -a, when investigating a failed job, an old test container or a container that has just exited:

docker ps --all

This includes every state that Docker can report, not just running. Look at the STATUS column for states such as Exited, Created or Restarting. The listing is observational: docker ps does not start, stop or remove anything, so there is no undo step.

The distinction between docker ps and docker ps -a is the most common source of a misleading incident check. If a service is absent from the first command, run the second before assuming it was never created.

3. Narrow the result with filters

The --filter option takes a quoted key=value expression. Filter by status when you want a clear operational question:

docker ps --all --filter "status=exited"
docker ps --filter "status=running"
docker ps --all --filter "name=web"
docker ps --all --filter "ancestor=nginx:latest"

The supported filters include id, name, label, exited, status, ancestor, before, since, volume, network, publish, expose, health and is-task. Some only make sense with --all. For example, an exit code belongs to a container that has finished:

docker ps --all --filter "exited=1"

A name filter matches all or part of a name, so name=web can return more than a container literally named web. Treat that as a search, not an exact comparison. Multiple filters are supplied as separate options:

docker ps --all --filter "status=exited" --filter "name=web"

4. Produce output for scripts

Use --quiet, or -q, when a later command needs only container IDs:

docker ps --quiet
docker ps --all --filter "status=exited" --quiet

Do not parse the human-oriented table when a script can consume IDs directly. The output contains one ID per line, and the default IDs are shortened. Request the complete identifiers when you need to compare them with logs, an API response or a stored value:

docker ps --no-trunc

For a stable, readable report, choose the columns explicitly with a Go template:

docker ps --format 'table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}'
docker ps --format '{{.ID}} {{.Names}} {{.Status}}'

Keep the single quotes around the template in a POSIX shell. They prevent the shell from interpreting the braces. The available fields are documented by Docker's formatting reference; if a field is not documented or does not exist in your installed version, do not build automation around it. Docker 29.8.1 also accepts --format json for JSON-formatted output, but verify the exact shape before writing a parser that must survive upgrades.

5. Inspect recent or latest containers

--latest, or -l, shows the latest created container and includes all states. It is useful after a command has created a container that exited immediately:

docker ps --latest
docker ps --latest --no-trunc

To see more recently created containers, use --last, or -n:

docker ps --last 5

These options concern creation order, not start time or current health. Use a status or health filter when the question is about availability. The default for --last is -1, so supply a positive number when you want a bounded report.

6. Check storage only when you need it

Add --size, or -s, to display each container's writable-layer size and virtual size:

docker ps --all --size

This can be useful when a container's writable layer may be growing, but it makes the query more expensive and adds noisy columns. It does not tell you the total size of every volume mounted into the container. Investigate volumes separately before treating this output as a complete disk-usage report.

Common traps and a safe routine

Start with docker ps. If the expected service is absent, run docker ps -a. If there are too many rows, filter by an exact status or a distinctive name fragment. If another command needs a target, use -q and consider --no-trunc. Use --format for reports and automation rather than cutting columns from the default table.

None of the commands in this guide changes container state, so there is nothing to roll back. Be more careful when copying an ID into a later command: inspection is safe, but commands such as docker rm, docker stop and docker kill change or destroy state and are outside this read-only workflow. Pause and verify the target before running one.

Done means

• You can distinguish the running-only view from docker ps -a.
• You can find exited containers with a status or exit-code filter.
• You can obtain IDs with --quiet and full IDs with --no-trunc.
• You can produce a deliberate report with --format.
• You know that listing commands are read-only, while later lifecycle commands may not be.