Read Docker Container State Fast with docker ps

Your service has gone quiet and docker ps shows nothing, but that does not mean nothing exists. This guide uses docker ps in about five minutes to answer the routine questions on a Docker host: what is running, what stopped, which container owns a name, and which IDs you can pass to another command. The examples were checked with Docker 29.8.1 from the docker-ce-cli package.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. List the containers that are running
2. Include stopped containers
3. Narrow the result with filters
4. Produce output for scripts
5. Inspect recent or latest containers
6. Check storage only when you need it
Common traps

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.

Security warning

Do not add sudo automatically. Docker access is privileged on many systems, so putting a user in 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, healthy-looking result can mean 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

Checkpoint

You know whether the daemon is reachable and you have seen the current running set. A daemon or permission error is an environment problem, not a filtering problem. Resolve it before changing flags.

2. Include stopped containers

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

docker ps --all

This includes every state 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.

Tip

The gap 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, 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 have 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. An exit code, for example, belongs to a container that has finished:

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

Name filters match parts. A name filter matches all or part of a name, so name=web can return more than a container literally called web. Treat it as a search, not an exact comparison. Multiple filters go in as separate options:

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

Checkpoint

If a filter unexpectedly returns nothing, repeat the query without it, inspect the exact name and status, then add one filter at a time. That way you are not debugging a misspelled value and an empty result at once.

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 is one ID per line, and the default IDs are shortened. Ask for 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}}'

Tip

Keep the single quotes around the template in a POSIX shell, so the shell does not interpret the braces. Docker's formatting reference documents the available fields. If a field is undocumented or missing in your installed version, do not build automation around it. Docker 29.8.1 also accepts --format json for JSON 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 handy after a command has created a container that exited immediately:

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

To see several 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 show each container's writable-layer size and virtual size:

docker ps --all --size

This helps when a writable layer may be growing, but it makes the query more expensive and adds noisy columns. It does not give 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

A safe routine, in order:

Start with docker ps.
Service missing? Run docker ps -a.
Too many rows? Filter by an exact status or a distinctive name fragment.
Another command needs a target? Use -q and consider --no-trunc.
Reports and automation? Use --format 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.

Warning

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

Running versus all. You can tell the running-only view from docker ps -a.
Exited found. You can find exited containers with a status or exit-code filter.
IDs on demand. You can get IDs with --quiet and full IDs with --no-trunc.
Deliberate reports. You can produce a report with --format.
Read-only mindset. You know that listing commands are read-only, while later lifecycle commands may not be.