docker ps Explained: List, Filter and Debug Containers

docker ps is the first command you reach for when a container is not doing what you expect. It lists the running containers on your Docker host, along with their IDs, images, ports and health status. If you have ever asked "is my container actually running?", this command answers it in one line.

What is docker ps?

docker ps queries the Docker daemon and prints a table of containers that are currently running. It is the CLI equivalent of the "Containers" view in Docker Desktop.

Basic syntax

docker ps [OPTIONS]

With no options it shows only running containers. Stopped containers are hidden — that surprises many people, so remember: if a container is not in the list, it may simply be stopped, not gone.

Common options

docker ps -a        # show all containers, including stopped ones
docker ps -q        # print only container IDs (useful for scripting)
docker ps -f status=exited   # filter: only exited containers
docker ps --format "table {{.Names}}\t{{.Status}}"  # custom columns

-q is the option I use most in scripts, for example to stop every stopped container in one command:

docker rm $(docker ps -aq -f status=exited)

Example: docker ps (real output)

Here is the actual output from my machine while I was debugging a ticket-generator project that uses Keycloak and PostgreSQL:

$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b7b51543e151 quay.io/keycloak/keycloak:26.0 "/opt/keycloak/bin/k…" 4 days ago Up 2 hours 8443/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 9000/tcp ticket_keycloak
e5311074829b postgres:17-alpine "docker-entrypoint.s…" 4 days ago Up 2 hours (healthy) 0.0.0.0:5434->5432/tcp, [::]:5434->5432/tcp ticket-generator-postgres

How to read the output

Troubleshooting: docker exec says "executable file not found"

While connecting to the Postgres container I first wrote the -it flags in the wrong position:

$ docker exec e5311074829b -it
OCI runtime exec failed: exec failed: unable to start container process: exec: "-it": executable file not found in $PATH: unknown

The error looks confusing, but the cause is simple: docker exec treats everything after the container name as the command to run inside the container. Placed there, -it was interpreted as a program name, and no program called -it exists.

Fix: the flags must come before the container name, and you must supply the actual command to run (here, psql):

docker exec -it e5311074829b psql -U dev_user -d ticket_generator_dev

Connecting to a Postgres container from the host

To connect with the host's psql, first confirm the environment variables the container was started with, because that is where the credentials live:

$ docker inspect e5311074829b | grep POSTGRES
 "POSTGRES_USER=dev_user",
 "POSTGRES_PASSWORD=dev_password",
 "POSTGRES_HOST_AUTH_METHOD=trust",
 "POSTGRES_DB=ticket_generator_dev"

Then connect through the published host port (5434, not the internal 5432):

$ psql -h localhost -p 5434 -U dev_user -d ticket_generator_dev
psql (14.19 (Ubuntu 14.19-0ubuntu0.22.04.1), server 17.6)
WARNING: psql major version 14, server major version 17.
 Some psql features might not work.
Type "help" for help.

The warning appears because the host psql is older than the server version inside the container. It is usually harmless — the connection works — but if you rely on newer PostgreSQL features, upgrade the host client or use docker exec to get the client version that matches the container image.

Common problems

Problem 1: docker ps shows nothing, but my container was running

Error: empty table, or only a header line.

Cause: the container stopped or restarted after a reboot; stopped containers are hidden by default.

Solution:

docker ps -a -f status=exited
docker logs <container-name> --tail 50

If it exits immediately on every start, the logs will tell you why. To make a container start again on boot, see how Docker restart policies work.

Problem 2: docker: command not found

Cause: Docker Engine is not installed, or the current user has no permission to talk to the daemon.

Solution: Install Docker, then add your user to the docker group and re-login:

sudo usermod -aG docker $USER

Problem 3: "Cannot connect to the Docker daemon"

Cause: the daemon is not running.

Solution:

sudo systemctl start docker
sudo systemctl enable docker

Best practices

Conclusion

docker ps answers "what is running and what is its state?" in a single glance. Read the STATUS and PORTS columns carefully — they explain most container mysteries — and when an exec error appears, check argument order before anything else.

Related Articles

A.M. Rinas

Written by A.M. Rinas

Full-Stack Software Engineer working on web applications, DevOps automation, and databases. More about me on the about page, or say hi through the contact page and LinkedIn.

← Back to all articles