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
- CONTAINER ID — short hash used to reference the container. Use it with
docker logs,docker execanddocker inspect. - IMAGE — the image the container was created from. Note the tag, e.g.
postgres:17-alpine. - STATUS — running time plus health. Here Postgres shows
(healthy), which means it passed its healthcheck; Keycloak has no healthcheck configured, so no flag appears. - PORTS — the port mapping.
0.0.0.0:5434->5432/tcpmeans: connect to port 5434 on your host and traffic is forwarded to port 5432 inside the container. - NAMES — the friendly name Docker assigned (or you gave with
--name). This is the safest value to use in commands.
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
- Always give containers a
--nameindocker runor in Compose; numeric IDs are easy to mistype. - Use
docker ps --formatto strip the table to the columns you actually need in scripts. - Put flags (
-it,-d) before the container name indocker exec— always. - Check
STATUSfor(healthy)to confirm readiness before connecting to databases. - Combine
docker ps -qwith filters for bulk cleanup; never kill containers by regex on names.
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.